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.

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 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.

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

GET /project
200 OK

Success

Response Example (200 OK)
{
  "id": "string (ProjectID)",
  "created_at": "string (date-time)",
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}

Edit project

PATCH /project
meta: Meta

Metadata for this object.

Request Example
{
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

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

GET /accounts
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

POST /accounts
currency: Currency
allow_negative_balance: boolean false
customer_id: string (CustomerID) null
meta: Meta

Metadata for this object.

Request Example
{
  "currency": "EUR",
  "allow_negative_balance": false,
  "customer_id": "string (CustomerID)",
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

Success

400 Bad Request

Bad request

type
object
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

GET /accounts/{account_id}
account_id: string (AccountID)
in path

Account ID

200 OK

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

PATCH /accounts/{account_id}
allow_negative_balance: boolean false
balance: Value

[SANDBOX ONLY] To make testing easier, you can directly change the balance of an account. Doing so will create Transactions with the type field set to magic.

meta: Meta

Metadata for this object.

account_id: string (AccountID)
in path

Account ID

Request Example
{
  "allow_negative_balance": "boolean",
  "balance": {
    "currency": "EUR",
    "amount": 100
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

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

GET /accounts/{account_id}/transactions
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

account_id: string (AccountID)
in path

Account ID

200 OK

Success

type
object
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

GET /transactions
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

GET /accounts/{account_id}/transactions
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

account_id: string (AccountID)
in path

Account ID

200 OK

Success

type
object
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

GET /transactions/{transaction_id}
transaction_id: string (TransactionID)
in path

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

GET /customers
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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",
        "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

POST /customers
identity: Identity
meta: Meta

Metadata for this object.

Request Example
{
  "identity": {
    "first_name": "John",
    "last_name": "McJohn",
    "email_address": "john@example.com",
    "phone_number": 34666555444,
    "nationality": "ES",
    "employment_status": "self_employed",
    "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"
  }
}
200 OK

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",
    "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

GET /customers/{customer_id}
customer_id: string (CustomerID)
in path

Customer ID

200 OK

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",
    "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

PATCH /customers/{customer_id}
identity: Identity
meta: Meta

Metadata for this object.

customer_id: string (CustomerID)
in path

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",
    "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"
  }
}
200 OK

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",
    "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

GET /transfers
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

POST /transfers
source_account_id: string (AccountID)
destination_account_id: string (AccountID)
value: Value
meta: Meta

Metadata for this object.

Request Example
{
  "source_account_id": "string (AccountID)",
  "destination_account_id": "string (AccountID)",
  "value": {
    "currency": "EUR",
    "amount": 100
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

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

GET /transfers/{transfer_id}
transfer_id: string (TransferID)
in path

Transfer ID

200 OK

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

PATCH /transfers/{transfer_id}
meta: Meta

Metadata for this object.

transfer_id: string (TransferID)
in path

Transfer ID

Request Example
{
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

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

POST /card_tokens
card_info: CardInfoRequest
Request Example
{
  "card_info": {
    "number": "4114360123456785",
    "expiration_month": 12,
    "expiration_year": 2023,
    "cvc": "123"
  }
}
200 OK

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

GET /card_tokens/{card_token_id}
card_token_id: string (CardTokenID)
in path

CardToken ID

200 OK

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

GET /cards
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

POST /cards
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"
  }
}
200 OK

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

GET /cards/{card_id}
card_id: string (CardID)
in path

Card ID

200 OK

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

PATCH /cards/{card_id}
meta: Meta

Metadata for this object.

card_id: string (CardID)
in path

Card ID

Request Example
{
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

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"
  }
}

SCA Cards 🇪🇺

SCA Cards contain card data stored in the Kernel Payments servers such as Cards do. Then why should you use these?.

SCA Cards has been introduced in order to support the set of regulations introduced by the second Payment Services Directive (PSD2) which aims to reduce fraudulent transactions.

These cards requires the cardholder to authenticate through a SCA compliant API, so that these must be provided later when creating ThreeDSecure 2 Card Payins that have the offline field set to true (i.e. cardholder did not initiate the transaction).

List SCA cards

GET /sca_cards
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
Response Example (200 OK)
{
  "data": [
    {
      "id": "string (SCACardID)",
      "created_at": "string (date-time)",
      "project_id": "string (ProjectID)",
      "customer_id": "string (CustomerID)",
      "authentication_url": "https://gateway.kernelpay.com/start/910932071",
      "authentication_redirect_url": "https://example.com/after-authentication",
      "state": "string",
      "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 SCA card

POST /sca_cards

If after 30 minutes no action has been performed in the authentication_url the SCA Card will be set with authentication_timeout state.

card_token_id: string (CardTokenID)
card_info: CardInfoRequest
card_id: string (CardID)
customer_id: string (CustomerID) null
authentication_redirect_url: string

URL to redirect to after authentication (optional).

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"
  },
  "card_id": "string (CardID)",
  "customer_id": "string (CustomerID)",
  "authentication_redirect_url": "https://example.com/after-authentication",
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

Success

Response Example (200 OK)
{
  "id": "string (SCACardID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "customer_id": "string (CustomerID)",
  "authentication_url": "https://gateway.kernelpay.com/start/910932071",
  "authentication_redirect_url": "https://example.com/after-authentication",
  "state": "string",
  "card_info": {
    "number": "string (card)",
    "expiration_month": 12,
    "expiration_year": 2023,
    "brand": "visa",
    "fingerprint": "yFe94Qso636auIaB"
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}

Get SCA card

GET /sca_cards/{sca_card_id}
sca_card_id: string (SCACardID)
in path

SCA card ID

200 OK

Success

Response Example (200 OK)
{
  "id": "string (SCACardID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "customer_id": "string (CustomerID)",
  "authentication_url": "https://gateway.kernelpay.com/start/910932071",
  "authentication_redirect_url": "https://example.com/after-authentication",
  "state": "string",
  "card_info": {
    "number": "string (card)",
    "expiration_month": 12,
    "expiration_year": 2023,
    "brand": "visa",
    "fingerprint": "yFe94Qso636auIaB"
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}

Edit SCA card

PATCH /sca_cards/{sca_card_id}
meta: Meta

Metadata for this object.

sca_card_id: string (SCACardID)
in path

SCA card ID

Request Example
{
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

Success

Response Example (200 OK)
{
  "id": "string (SCACardID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "customer_id": "string (CustomerID)",
  "authentication_url": "https://gateway.kernelpay.com/start/910932071",
  "authentication_redirect_url": "https://example.com/after-authentication",
  "state": "string",
  "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

GET /card_payins
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
Response Example (200 OK)
{
  "data": [
    {
      "id": "string (CardPayinID)",
      "created_at": "string (date-time)",
      "project_id": "string (ProjectID)",
      "state": "string",
      "card_id": "string (CardID)",
      "sca_card_id": "string (SCACardID)",
      "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

POST /card_payins
authentication_type: string none, three_d_secure, three_d_secure_2

Type of authentication (None, 3DSecure or 3DSecure 2 which is SCA 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)
sca_card_id: string (SCACardID)
offline: bool

Only can be used for three_d_secure_2 charges where the customer is not present. A sca_card_id must be provided.

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)",
  "sca_card_id": "string (SCACardID)",
  "offline": "bool",
  "account_id": "string (AccountID)",
  "statement_descriptor_suffix": "string",
  "value": {
    "currency": "EUR",
    "amount": 100
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

Success

Response Example (200 OK)
{
  "id": "string (CardPayinID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "state": "string",
  "card_id": "string (CardID)",
  "sca_card_id": "string (SCACardID)",
  "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

GET /card_payins/{card_payin_id}
card_payin_id: string (CardPayinID)
in path

CardPayin ID

200 OK

Success

Response Example (200 OK)
{
  "id": "string (CardPayinID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "state": "string",
  "card_id": "string (CardID)",
  "sca_card_id": "string (SCACardID)",
  "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

PATCH /card_payins/{card_payin_id}
meta: Meta

Metadata for this object.

card_payin_id: string (CardPayinID)
in path

CardPayin ID

Request Example
{
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

Success

Response Example (200 OK)
{
  "id": "string (CardPayinID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "state": "string",
  "card_id": "string (CardID)",
  "sca_card_id": "string (SCACardID)",
  "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

GET /card_payins/{card_payin_id}/refunds
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

card_payin_id: string (CardPayinID)
in path

CardPayin ID

200 OK

Success

type
object
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

POST /card_payins/{card_payin_id}/refunds
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.

card_payin_id: string (CardPayinID)
in path

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

POST /card_payins/{card_payin_id}/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.

card_payin_id: string (CardPayinID)
in path

CardPayin ID

Request Example
"object"
200 OK

Success

Response Example (200 OK)
{
  "id": "string (CardPayinID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "state": "string",
  "card_id": "string (CardID)",
  "sca_card_id": "string (SCACardID)",
  "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

POST /card_payins/{card_payin_id}/cancel

Card payins that are in authentication_pending state can be cancelled to prevent the user takes further action.

card_payin_id: string (CardPayinID)
in path

CardPayin ID

200 OK

Success

Response Example (200 OK)
{
  "id": "string (CardPayinID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "state": "string",
  "card_id": "string (CardID)",
  "sca_card_id": "string (SCACardID)",
  "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

GET /bank_accounts
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

POST /bank_accounts
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

GET /bank_accounts/{bank_account_id}
bank_account_id: string (BankAccountID)
in path

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

PATCH /bank_accounts/{bank_account_id}
meta: Meta

Metadata for this object.

bank_account_id: string (BankAccountID)
in path

BankAccount ID

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

GET /bank_payouts
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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
      },
      "meta": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  ],
  "has_next": true,
  "cursor_next": "string (cursor)"
}

Create bank payout

POST /bank_payouts
account_id: string (AccountID)
bank_account_id: string (BankAccountID)
concept: string
value: Value
meta: Meta

Metadata for this object.

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
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}

Get bank payout

GET /bank_payouts/{bank_payout_id}
bank_payout_id: string (BankPayoutID)
in path

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
  },
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}

Edit bank payout

PATCH /bank_payouts/{bank_payout_id}
allow_negative_balance: boolean false
meta: Meta

Metadata for this object.

bank_payout_id: string (BankPayoutID)
in path

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
  },
  "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

GET /bank_payins
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

GET /bank_payins/{bank_payin_id}
bank_payin_id: string (BankPayinID)
in path

BankPayin ID

200 OK

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

PATCH /bank_payins/{bank_payin_id}
meta: Meta

Metadata for this object.

bank_payin_id: string (BankPayinID)
in path

BankPayin ID

Request Example
{
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}
200 OK

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

GET /bank_payin_references
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

POST /bank_payin_references
account_id: string (AccountID)

Funds from BankPayins with this reference will be credited to this account.

meta: Meta

Metadata for this object.

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

GET /bank_payin_references/{bank_payin_reference_id}
bank_payin_reference_id: string (BankPayinReferenceID)
in path

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

PATCH /bank_payin_references/{bank_payin_reference_id}
account_id: string (AccountID)

Funds from BankPayins with this reference will be credited to this account.

meta: Meta

Metadata for this object.

bank_payin_reference_id: string (BankPayinReferenceID)
in path

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

POST /files
200 OK

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

GET /files/{file_id}
file_id: string (fileID)
in path

File ID

200 OK

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

GET /events
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

GET /events/{event_id}
event_id: string (EventID)
in path

Event ID

200 OK

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

GET /webhooks
limit: integer
in query

How many items to return, at maximum.

cursor: integer
in query

Cursor, to fetch more pages of a long list. See Pagination

200 OK

Success

type
object
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

POST /webhooks
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 and https.

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
}
200 OK

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

GET /webhooks/{webhook_id}
webhook_id: string (WebhookID)
in path

Webhook ID

200 OK

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

PATCH /webhooks/{webhook_id}
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 and https.

is_enabled: boolean

Whether this webhook is enabled or not. Disabled webhooks do not send notifications, and can be re-enabled later.

webhook_id: string (WebhookID)
in path

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
}
200 OK

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

DELETE /webhooks/{webhook_id}
webhook_id: string (WebhookID)
in path

Webhook ID

200 OK

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

Meta: object

string
Example
{
  "key1": "value1",
  "key2": "value2"
}

Currency: string

string EUR

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"
  }
}

Project: object

id: string (ProjectID)

Unique identifier

created_at: string (date-time)

Creation time for this object

meta: Meta

Metadata for this object.

Example
{
  "id": "string (ProjectID)",
  "created_at": "string (date-time)",
  "meta": {
    "key1": "value1",
    "key2": "value2"
  }
}

Customer: object

id: string (CustomerID)

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..

identity: Identity

Customer identity. Optional.

meta: Meta

Metadata for this 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",
    "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.

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",
  "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)"
  }
}

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, not 19)

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, not 19)

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

id: string (CardTokenID)

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_info: CardInfo
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"
  }
}

SCACard: object

id: string (SCACardID)

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.

authentication_url: string

URL to perform authentication

authentication_redirect_url: string

URL to redirect to after authentication.

state: string processing, authorized, declined, authentication_pending, authentication_timeout
card_info: CardInfo
meta: Meta

Metadata for this object.

Example
{
  "id": "string (SCACardID)",
  "created_at": "string (date-time)",
  "project_id": "string (ProjectID)",
  "customer_id": "string (CustomerID)",
  "authentication_url": "https://gateway.kernelpay.com/start/910932071",
  "authentication_redirect_url": "https://example.com/after-authentication",
  "state": "string",
  "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 processed
  • authorized: 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 when authentication_type is three_d_secure or three_d_secure_2 and not offline.
  • cancelled: The card payin which was in authentication_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, CardToken or sca_card_id.

sca_card_id: string (SCACardID)

SCA Card used for the payment. Non-null if the CardPayin was created with a SCA Card, null if the CardPayin was created with card_info, CardToken or card_id.

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 is settled.

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)",
  "sca_card_id": "string (SCACardID)",
  "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 is failed or refunded.

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.

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
  },
  "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)",
    "sca_card_id": "string (SCACardID)",
    "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
    },
    "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
    },
    "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
    },
    "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)",
    "sca_card_id": "string (SCACardID)",
    "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)",
    "sca_card_id": "string (SCACardID)",
    "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 and https.

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
}