NAV navbar
logo
curl
Core Partner API
API Endpoint
https://partner.finiata.com/v1

Getting Started

Welcome to the Core Partner API Documentation. The Core Partner API allows you to connect your application to our backend to deeply integrate a invoice financing solution into your product.

The partner API is organized around REST. The API provides predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

To make the API as explorable as possible, partners receive test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test requests. Requests made with test mode credentials never hit the banking networks and incur no cost.

Authentication

Authenticate your requests when using the API by including your secret partner key in the request. API keys are managed by Finiata's integration team. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via an authentication token, namely the Partner Key. Provide your API key as the X-Auth-Partner-Key header value. You do not need to provide a password.

Errors

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xxrange indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with our servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a financing of an invoice is declined), we return a 402 error code. To understand why an invoice is declined, refer to the list of codes in the documentation.

Customers

The customer object represents an entity who writes invoices and requests the financing of those. You need to create a new customer, in order to push and finance invoices. Being an identity provider for the shared customer, the customer object is further needed for creation sessions in the customers name.

Customers POST

This endpoint creates a new customer object. This is the first step in starting a business relationship between us and a customer and a requirement for all further customer-related actions. This is especially true for the creation of invoices, as well as the financing of those. Along with the customer, a vendor_id may be passed. This is an identifier used on your end to refer to the customer. Submitting this can make your life easier, using the vendor_id and the provided api_key we might be granted access to your API to access data on the customer's behalf.

Query Parameters
  • vendor_id string

    Unique identifier for the object in your system.

  • api_key string

    API key to allow accessing your API. This can be useful for session creation or to pull data regarding the customer instead of pushing it.

  • salutation string

    Enum. representing the customers gender. Acceptable values are ["f", "m"].

  • firstname string

    The customer's firstname or firstnames in case of multiple names.

  • lastname string

    The customer's lastname.

  • email string

    The customer’s email address.

  • mobilephone string

    The customer’s mobile phone numer.

  • company.name string

    The customer's company name. In case of a legal entity, this holds the full legal name including the legal form. In case of a sole trader or proprietorship, this company name may hold the name, under which the customer operates his business.

  • company.legal_form string

    The customer company's legal form.

  • company.vat_exempt boolean

    A flag for whether or not the customer holds a VAT exempt allowing him/her to not charge any VAT.

  • company.vat_id string

    The customer company's VAT identification number.

  • company.tax_id string

    The customer company's tax identification number.

  • company.foundation_date string

    The foundation date of the company in ISO 8601 fromat, e.g. '2017-01-01'

  • company.address string

    The street address of the customer's company. This includes the house number.

  • company.address_additional string

    An optional line for the street address.

  • company.postal_code string

    The postal code of the customer company's address.

  • company.city string

    The city of the customer company's address.

  • company.country_code string

    Two-character string representing the customer company's country in ISO 3166 (Alpha 2) format, e.g. 'DE'

Definition
POST /customers
Example Request
{
  "vendor_id": "12345678",
  "api_key": "1234567890ab",
  "salutation": "f",
  "firstname": "Louane",
  "lastname": "Vitaly",
  "email": "louane.vidal@example.com",
  "mobilephone": "+4915111223344",
  "company": {
    "name": "Louane Vidal Sp. z o.o.",
    "legal_form": "Sp. z o.o.",
    "vat_exempt": false,
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "foundation_date": "2016-07-15",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Krakow",
    "country_code": "PL"
  }
}
Example Response
{
  "id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "vendor_id": "12345678",
  "api_key": "1234567890ab",
  "salutation": "f",
  "firstname": "Louane",
  "lastname": "Vitaly",
  "email": "louane.vidal@example.com",
  "mobilephone": "+4915111223344",
  "company": {
    "name": "Louane Vidal Sp. z o.o.",
    "legal_form": "Sp. z o.o.",
    "vat_exempt": false,
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "foundation_date": "2016-07-15",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Krakow",
    "country_code": "PL"
  }
}
Possible Responses
200 - OK 
422 - Unprocessable Entity 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Customers GET

Retrieves all stored details of an existing customer. You only need to supply the unique customer identifier customer_id. By default this is our internal identifier, that has been provided to you with the creation of a customer.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Definition
GET /customers/{customer_id}
Example Response
{
  "id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "vendor_id": "12345678",
  "api_key": "1234567890ab",
  "salutation": "f",
  "firstname": "Louane",
  "lastname": "Vitaly",
  "email": "louane.vidal@example.com",
  "mobilephone": "+4915111223344",
  "company": {
    "name": "Louane Vidal Sp. z o.o.",
    "legal_form": "Sp. z o.o.",
    "vat_exempt": false,
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "foundation_date": "2016-07-15",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Krakow",
    "country_code": "PL"
  }
}
Possible Responses
200 - OK 
404 - Not FoundCustomer with given identifier not found. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Customers PATCH

Updates an existing customer object. You need to supply the unique customer identifier customer_id. By default this is our internal identifier, that has been provided to you with the creation of a customer.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • vendor_id string

    Unique identifier for the object in your system.

  • api_key string

    API key to allow accessing your API. This can be useful for session creation or to pull data regarding the customer instead of pushing it.

  • salutation string

    Enum. representing the customers gender. Acceptable values are ["f", "m"].

  • firstname string

    The customer's firstname or firstnames in case of multiple names.

  • lastname string

    The customer's lastname.

  • email string

    The customer’s email address.

  • mobilephone string

    The customer’s mobile phone numer.

  • company.name string

    The customer's company name. In case of a legal entity, this holds the full legal name including the legal form. In case of a sole trader or proprietorship, this company name may hold the name, under which the customer operates his business.

  • company.legal_form string

    The customer company's legal form.

  • company.vat_exempt boolean

    A flag for whether or not the customer holds a VAT exempt allowing him/her to not charge any VAT.

  • company.vat_id string

    The customer company's VAT identification number.

  • company.tax_id string

    The customer company's tax identification number.

  • company.foundation_date string

    The foundation date of the company in ISO 8601 format, e.g. 2017-01-01

  • company.address string

    The street address of the customer's company. This includes the house number.

  • company.address_additional string

    An optional line for the street address.

  • company.postal_code string

    The postal code of the customer company's address.

  • company.city string

    The city of the customer company's address.

  • company.country_code string

    Two-character string representing the customer company's country in ISO 3166 (Alpha 2) format, e.g. DE

Definition
PATCH /customers/{customer_id}
Example Request
{
  "vendor_id": "12345678",
  "api_key": "1234567890ab",
  "salutation": "f",
  "firstname": "Louane",
  "lastname": "Vitaly",
  "email": "louane.vidal@example.com",
  "mobilephone": "+4915111223344",
  "company": {
    "name": "Louane Vidal Sp. z o.o.",
    "legal_form": "Sp. z o.o.",
    "vat_exempt": false,
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "foundation_date": "2016-07-15",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Krakow",
    "country_code": "PL"
  }
}
Example Response
{
  "id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "vendor_id": "12345678",
  "api_key": "1234567890ab",
  "salutation": "f",
  "firstname": "Louane",
  "lastname": "Vitaly",
  "email": "louane.vidal@example.com",
  "mobilephone": "+4915111223344",
  "company": {
    "name": "Louane Vidal Sp. z o.o.",
    "legal_form": "Sp. z o.o.",
    "vat_exempt": false,
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "foundation_date": "2016-07-15",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Krakow",
    "country_code": "PL"
  }
}
Possible Responses
200 - OK 
404 - Not FoundCustomer with given identifier not found. 
422 - Unprocessable Entity 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Sessions

A customer sessions will allow the customer to access the user interface. If you act as an identity provider, authentication must be performed on your end. To redirect an authenticated customer, a session must first be created. This endpoint allows for initializing and listing customer sessions.

Sessions POST

Initializes a customer session and responds with a session_token as well as a redirect_url where the session token is appended to the query parameters.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • redirection_url string

    Optional redirection url that the customer should be forwarded to. Passed URLs are validated and only used if they belong to the correct domain. If it is omitted, the default URL is returned which leads the user to the dashboard.

  • exit_url string

    Optional exit url that the customer should be forwarded to when exiting our application. Passed URLs are validated and only used if they belong to the correct domain. If it is omitted, the default URL is returned which leads the user to the dashboard.

Definition
POST /customers/{customer_id}/sessions
Example Request
{
  "redirection_url": "https://www.finiata.com/invoice/i-fesd-0000-1234-4321-1234567890ab",
  "exit_url": "https://www.example-partner.com/dashboard"
}
Example Response
{
  "redirection_url": "https://www.finiata.com/authentication/token-abcdef00-0000-1234-4321-1234567890ab?target=https%3A%2F%2Fwww.finiata.com%2Finvoice%2Fi-fesd-0000-1234-4321-1234567890ab"
}
Possible Responses
200 - OKReturns a session token. 
400 - Bad RequestBad request: check content-type and ensure that request body is in _'application/json'_  
403 - ForbiddenCustomer access denied: Customer is blocked from Finiata's side. Session creation request is denied.  
404 - Not FoundThe customer could not be found. 
406 - Not acceptableThe request is not acceptable. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Sessions GET

Retrieves customer_id by session token. This can be useful in case you have a session_token stored, but you don't know which of your customers it belongs to. Response includes only the internal customer_id itself as well as your customer_external_id.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • session_token string

    Use this identifier to query a specific session. By default the passed identifier refers to our internal session token.

Definition
GET /customers/{customer_id}/sessions/{session_token}
Example Response
{
  "customer_id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "customer_external_id": "12345678"
}
Possible Responses
200 - OKReturns `customer_id` and `customer_external_id` of customer who bears the requested session_token. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Credit Limit

This endpoint can be called on a specific customer to retrieve the status and details about the customer's credit limit.

Credit Limit GET

Retrieves the customer's credit limit by the customer_id. A credit limit is associated to each customer after completed onboarding. Before the credit limit is associated, the status will return pending_onboarding as long as the customer did not finish the onboarding or processing when the credit limit is being processed. In pending_onboarding, the customer should be asked to finish the onboarding by forwarding him to the Finiata application. As soon as the status turns to available. Then, the response includes details including the total credit limit, the available credit limit as well as the current outstanding. If a credit limit is available but exhausted, the status changes to exhausted.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Definition
GET /customers/{customer_id}/credit_limit
Example Response
{
  "status": "available",
  "credit_limit_cents": 156000,
  "outstanding_cents": 50000,
  "available_cents": 106000
}
Possible Responses
200 - OKA credit limit is available and the details are provided in the response. 
202 - AcceptedNo credit limit is available yet. The reponse most likely has a status of pending_onboarding. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Invoices

The invoice object represents an invoice document. Invoice are always owned by a customer and are pushed to Finiata for at least one of two reasons: 1. Pushed invoices that are not yet paid and not yet overdue are potential candidates for financing. These invoices can be submitted to the financing process. 2. Invoices of any kind are considered by the scoring engine. Invoices can therefore be pushed to Finiata to increase the acceptance propability. In order to push and finance invoices you need to create a new customer. Being an identity provider for the shared customer, the customer object is further needed for creation sessions in the customers name.

Invoices POST

This requests creates a new invoice for the customer identified by customer_id. Along with the customer, a vendor_id may be passed. This is an identifier used on your end to refer to the invoice. Using the vendor_id of the invoice and the provided api_key on the customer level, we might be granted access to your API to access invoice related data on the customer's behalf.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • vendor_id string

    Unique identifier for the object in your system.

  • number string

    Unique (string-) identifier of the invoice usually provided by the customer and used for accounting purposes. This string is used in all invoice related communication towards the customer.

  • amount_cents integer

    Invoice total amount including VAT. It is required if no invoice items are given. It will be overwritten (recalculated from item amounts), if items are given.

  • currency_code string

    Currency code in ISO 4217 format, e.g. 'EUR'

  • issue_date string

    Date of the invoice issuance in ISO 8601 fromat, e.g. 2017-01-01

  • delivery_date_from string

    Beginning date of the delivery interval of the invoiced good or service in ISO 8601 fromat, e.g. '2017-01-01'. In case the delivery time is not an interval, this field serves as the delivery date.

  • delivery_date_to string

    Ending date of the delivery interval in ISO 8601 fromat, e.g. 2017-01-01. Can be ommitted if the delivery has been made on a specific date.

  • due_date string

    Due date of the invoice in ISO 8601 fromat, e.g. 2017-01-01 when the payment of the invoice is expected.

  • comment string

    Optional invoice comment.

  • recipient.name string

    The recipient's company name. In case of a legal entity, this holds the full legal name including the legal form. In case of a sole trader or proprietorship, this name may hold the name, under which the recipient operates his business. In case of a private individual, the name can be omitted.

  • recipient.legal_form string

    Legal form of the invoice recipient.

  • recipient.salutation string

    Enum. representing the customers gender. Acceptable values are ["f", "m"].

  • recipient.firstname string

    The firstname of the invoice recipient.

  • recipient.lastname string

    The lastname of the invoice recipient.

  • recipient.phone string

    The phone number of the invoice recipient.

  • recipient.email string

    The email address of the invoice recipient.

  • recipient.tax_id string

    The tax id of the invoice recipient.

  • recipient.vat_id string

    The vat_id of the invoice recipient.

  • recipient.address string

    The street address of the recipient. This includes the house number.

  • recipient.address_additional string

    An optional line for the street address.

  • recipient.postal_code string

    The postal code of the recipients address.

  • recipient.city string

    The city of the customer company's address.

  • recipient.country_code string

    Country code in ISO 3166 (Alpha 2) format, e.g. 'DE'

  • items.article_number string

    Article number of the invoice item.

  • items.description string

    Description of the invoice item.

  • items.quantity number

    The quantity of the invoice item.

  • items.net_unit_price_cents number

    The net price per unit (without VAT) of the invoice item.

  • items.vat_percent number

    The percentage of VAT to be added to the net price per unit.

  • pdf_url string

    An accessible (by our servers, not necessarily public) url that serves a pdf document representing the invoice.

Definition
POST /customers/{customer_id}/invoices
Example Request
{
  "vendor_id": "12345678",
  "number": "INV-123",
  "amount_cents": 1234,
  "currency_code": "EUR",
  "issue_date": "2017-01-15",
  "delivery_date_from": "2017-01-01",
  "delivery_date_to": "2017-01-15",
  "due_date": "2017-01-30",
  "comment": "",
  "recipient": {
    "name": "Ruben Stone UG",
    "legal_form": "ug",
    "salutation": "m",
    "firstname": "Ruben",
    "lastname": "Stone",
    "phone": "+4915111223344",
    "email": "ruben.stone@example.com",
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Berlin",
    "country_code": "DE"
  },
  "items": [
    {
      "article_number": "A-1",
      "description": "Article one",
      "quantity": 3.3,
      "net_unit_price_cents": 1223,
      "vat_percent": 19.00
    }
  ],
  "pdf_url": "https://yourservers.tld/uri-to-your-invoice.pdf"
}
Example Response
{
  "id": "invoice-fesd-0000-1234-4321-1234567890ab",
  "vendor_id": "12345678",
  "customer_id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "resource_url": "http://www.finiata.com/invoice/fesd-0000-1234-4321-1234567890ab",
  "number": "INV-123",
  "amount_cents": 1234,
  "currency_code": "EUR",
  "issue_date": "2017-01-15",
  "delivery_date_from": "2017-01-01",
  "delivery_date_to": "2017-01-15",
  "due_date": "2017-01-30",
  "comment": "",
  "recipient": {
    "name": "Ruben Stone UG",
    "legal_form": "ug",
    "salutation": "m",
    "firstname": "Ruben",
    "lastname": "Stone",
    "phone": "+4915111223344",
    "email": "ruben.stone@example.com",
    "vat_id": "DE123123123",
    "tax_id": "DE123123123",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Berlin",
    "country_code": "DE"
  },
  "items": [
    {
      "article_number": "A-1",
      "description": "Article one",
      "quantity": 12.34,
      "net_unit_price_cents": 1234,
      "vat_percent": 19.00
    }
  ]
}
Possible Responses
200 - OKInvoice successfully stored. 
422 - Unprocessable EntityInvoice details unprocessable - validation failed. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Invoices DELETE

Deletes an invoice by the invoice_id. By default this is our internal identifier, that has been provided to you with the creation of an invoice.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • invoice_id string

    Use this identifier to query a specific invoice. By default the passed identifier refers to our internal id.

Definition
DELETE /customers/{customer_id}/invoices/{invoice_id}
Possible Responses
200 - OKInvoice is deleted. 
403 - ForbiddenInvoice can't be deleted. 
404 - Not FoundInvoice with given identifier not found. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Invoices GET

Retrieves an invoice including all of its details by the invoice_id. By default this is our internal identifier, that has been passed to you with the creation of an invoice.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • invoice_id string

    Use this identifier to query a specific invoice. By default the passed identifier refers to our internal id.

Definition
GET /customers/{customer_id}/invoices/{invoice_id}
Example Response
{
  "id": "invoice-fesd-0000-1234-4321-1234567890ab",
  "vendor_id": "12345678",
  "customer_id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "resource_url": "http://www.finiata.com/invoice/fesd-0000-1234-4321-1234567890ab",
  "number": "INV-123",
  "amount_cents": 1234,
  "currency_code": "EUR",
  "issue_date": "2017-01-15",
  "delivery_date_from": "2017-01-01",
  "delivery_date_to": "2017-01-15",
  "due_date": "2017-01-30",
  "comment": "",
  "recipient": {
    "name": "Ruben Stone UG",
    "legal_form": "ug",
    "salutation": "m",
    "firstname": "Ruben",
    "lastname": "Stone",
    "phone": "+4915111223344",
    "email": "ruben.stone@example.com",
    "vat_id": "DE123123123",
    "tax_id": "DE123123123",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Berlin",
    "country_code": "DE"
  },
  "items": [
    {
      "article_number": "A-1",
      "description": "Article one",
      "quantity": 12.34,
      "net_unit_price_cents": 1234,
      "vat_percent": 19.00
    }
  ]
}
Possible Responses
200 - OK 
404 - Not FoundInvoice with given identifier not found. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Invoices PATCH

Updates the details of an existing invoice. This is only possible if the invoice has not yet been submitted to financing by \finance. The invoices id needs to be provided in the URI. By default this is our internal identifier, that has been passed to you with the creation of an invoice.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • invoice_id string

    Use this identifier to query a specific invoice. By default the passed identifier refers to our internal id.

Query Parameters
  • vendor_id string

    Unique identifier for the object in your system.

  • number string

    Unique (string-) identifier of the invoice usually provided by the customer and used for accounting purposes. This string is used in all invoice related communication towards the customer.

  • amount_cents integer

    Invoice total amount including VAT. It is required if no invoice items are given. It will be overwritten (recalculated from item amounts), if items are given.

  • currency_code string

    Currency code in ISO 4217 format, e.g. 'EUR'

  • issue_date string

    Date of the invoice issuance in ISO 8601 fromat, e.g. '2017-01-01'

  • delivery_date_from string

    Beginning date of the delivery interval of the invoiced good or service in ISO 8601 fromat, e.g. '2017-01-01'. In case the delivery time is not an interval, this field serves as the delivery date.

  • delivery_date_to string

    Ending date of the delivery interval in ISO 8601 fromat, e.g. '2017-01-01'. Can be ommitted if the delivery has been made on a specific date.

  • due_date string

    Due date of the invoice in ISO 8601 fromat, e.g. '2017-01-01' when the payment of the invoice is expected.

  • comment string

    Optional invoice comment.

  • recipient.name string

    The recipient's company name. In case of a legal entity, this holds the full legal name including the legal form. In case of a sole trader or proprietorship, this name may hold the name, under which the recipient operates his business. In case of a private individual, the name can be omitted.

  • recipient.legal_form string

    Legal form of the invoice recipient.

  • recipient.salutation string

    Enum. representing the customers gender. Acceptable values are ["f", "m"].

  • recipient.firstname string

    The firstname of the invoice recipient.

  • recipient.lastname string

    The lastname of the invoice recipient.

  • recipient.phone string

    The phone number of the invoice recipient.

  • recipient.email string

    The email address of the invoice recipient.

  • recipient.address string

    The street address of the recipient. This includes the house number.

  • recipient.address_additional string

    An optional line for the street address.

  • recipient.postal_code string

    The postal code of the recipients address.

  • recipient.city string

    The city of the customer company's address.

  • recipient.country_code string

    Country code in ISO 3166 (Alpha 2) format, e.g. 'DE'

  • items.article_number string

    Article number of the invoice item.

  • items.description string

    Description of the invoice item.

  • items.quantity number

    The quantity of the invoice item.

  • items.net_unit_price_cents number

    The net price per unit (without VAT) of the invoice item.

  • items.vat_percent number

    The percentage of VAT to be added to the net price per unit.

  • pdf_url string

    An accessible (by our servers, not necessarily public) url that serves a pdf document representing the invoice.

Definition
PATCH /customers/{customer_id}/invoices/{invoice_id}
Example Request
{
  "vendor_id": "12345678",
  "number": "INV-123",
  "amount_cents": 1234,
  "currency_code": "EUR",
  "issue_date": "2017-01-15",
  "delivery_date_from": "2017-01-01",
  "delivery_date_to": "2017-01-15",
  "due_date": "2017-01-30",
  "comment": "",
  "recipient": {
    "name": "Ruben Stone UG",
    "legal_form": "ug",
    "salutation": "m",
    "firstname": "Ruben",
    "lastname": "Stone",
    "phone": "+4915111223344",
    "email": "ruben.stone@example.com",
    "vat_id": "De123123123",
    "tax_id": "DE123123123",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Berlin",
    "country_code": "DE"
  },
  "items": [
    {
      "article_number": "A-1",
      "description": "Article one",
      "quantity": 3.3,
      "net_unit_price_cents": 1223,
      "vat_percent": 19.00
    }
  ],
  "pdf_url": "https://yourservers.tld/uri-to-your-invoice.pdf"
}
Example Response
{
  "id": "invoice-fesd-0000-1234-4321-1234567890ab",
  "vendor_id": "12345678",
  "customer_id": "customer-abcdef00-0000-1234-4321-1234567890ab",
  "resource_url": "http://www.finiata.com/invoice/fesd-0000-1234-4321-1234567890ab",
  "number": "INV-123",
  "amount_cents": 1234,
  "currency_code": "EUR",
  "issue_date": "2017-01-15",
  "delivery_date_from": "2017-01-01",
  "delivery_date_to": "2017-01-15",
  "due_date": "2017-01-30",
  "comment": "",
  "recipient": {
    "name": "Ruben Stone UG",
    "legal_form": "ug",
    "salutation": "m",
    "firstname": "Ruben",
    "lastname": "Stone",
    "phone": "+4915111223344",
    "email": "ruben.stone@example.com",
    "vat_id": "DE123123123",
    "tax_id": "DE123123123",
    "address": "Street",
    "address_additional": "",
    "postal_code": "10000",
    "city": "Berlin",
    "country_code": "DE"
  },
  "items": [
    {
      "article_number": "A-1",
      "description": "Article one",
      "quantity": 12.34,
      "net_unit_price_cents": 1234,
      "vat_percent": 19.00
    }
  ]
}
Possible Responses
200 - OK 
403 - ForbiddenInvoice can't be updated. 
404 - Not FoundInvoice not found. 
422 - Unprocessable Entity 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

States POST

Check invoice states. This is meant for you to check a list of invoices for current state and/or if the invoice can be processed. This can for example be used to display buttons/states in your interface accordingly. The endpoint therefore serves to different purposes.

State of an Existing Invoice Object

If you want to refer to an existing invoice in our system, the id, our internal identifier for the object needs to be passed in the payload. If invoice is found, optional parameters are ignored and the current state of the invoice will be returned.

The following states can be returned:

StateDescription
draftThe invoice has not been submitted for financing yet
invalidThe invoice has not been submitted for financing yet and is not eligible for financing
correctionThe has been submitted for financing, but there is more information needed for processing
in_progressThe invoice is being processed
offerThere is an offer available for the invoice
confirmationAn offer has been accepted, but further confirmation is required for the invoice claim
confirmation_checkFurther confirmation has been provided and is being processed
processing_payoutFurther confirmation has been provided and is being processed
paid_outThe loan has been paid out
graceThe loan should have been paid back but we are grace
overdueThe loan is overdue
collectionThe loan is in collection
completeThe loan has been repaid
rejectedThe invoice has been rejected by Finiata
declinedThe offer has been declined by the user

Financeability Check

If no id is provided or the invoice could not be found, optional parameters are used to check if invoice can be processed. The following results can be returned:

IdentifierDescription
unprocessable_currencyCurrency not accepted
due_date_too_far_in_the_pastDue date too far in the past
due_date_too_far_in_the_futureDue date too far in the future
invoice_total_too_smallInvoice amount too small
invoice_date_in_the_futureIssue date can't be in the future
invoice_date_after_due_dateIssue date cannot be after the due date
delivery_too_far_in_the_pastDelivery date is too far in the past
URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • id string

    The unique identifier of the invoice for which to retreive the current state.

  • amount_cents integer

    The invoices total amount in cents.

  • currency_code string

    Currency code in ISO 4217 format, e.g. 'EUR'

  • due_date string

    Due date of the invoice in ISO 8601 fromat, e.g. '2017-01-01' when the payment of the invoice is expected.

  • delivery_date_from string

    Beginning date of the delivery interval of the invoiced good or service in ISO 8601 fromat, e.g. '2017-01-01'. In case the delivery time is not an interval, this field serves as the delivery date.

  • delivery_date_to string

    Ending date of the delivery interval in ISO 8601 fromat, e.g. '2017-01-01'. Can be ommitted if the delivery has been made on a specific date.

Definition
POST /customers/{customer_id}/invoices/states
Example Request
{
  "invoices": [
    {
      "id": "123"
    },
    {
      "id": "234",
      "amount_cents": 123456,
      "currency_code": "USD",
      "due_date": "2009-01-31",
      "issue_date": "2009-01-01",
      "delivery_date_from": "2009-01-15"
    },
    {
      "id": "345",
      "amount_cents": 223344,
      "currency_code": "EUR",
      "due_date": "2020-06-15"
    },
    {
      "id": "456"
    }
  ]
}
Example Response
{
  "results": [
    {
      "id": "123",
      "state": "in_progress"
    },
    {
      "id": "234",
      "state": "not_factorable",
      "reasons": ["already_overdue", "unprocessable_currency"]
    },
    {
      "id": "345",
      "state": "factorable",
      "days_left": 7
    },
    {
      "id": "456",
      "state": "not_found"
    }
  ]
}
Possible Responses
200 - OK 
400 - Bad RequestBad Request 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Offers

For each invoice, different offers are available out of which the partner or customer may choose one.

Offers POST

The endpoint returns all available offers for an earlier submitted invoice. It may be used to provide a even more specific interface to the customer for choosing an offer prior to submitting the invoice for financing. The chosen offer's id then needs to be passed along when submitting an invoice to financing through the /finance endpoint.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • invoice_id string

    The unique identifier of the invoice for which to retrieve offers.

Definition
POST /customers/{customer_id}/offers
Example Request
{
  "invoice_id": "invoice-fesd-0000-1234-4321-1234567890ab",
}
Example Response
{
  "offers": [
    {
      "id": "offer-fesd-0000-1234-4321-1234567890ab",
      "advance_cents": 95000,
      "fee_cents": 5000,
      "payback_cents": 100000,
      "days": 30,
      "due_date": "2017-01-15"
    },
    {
      "id": "offer-fesd-0000-1234-4321-1234567890ab",
      "advance_cents": 90000,
      "fee_cents": 10000,
      "payback_cents": 100000,
      "days": 60,
      "due_date": "2017-02-15"
    },
    {
      "id": "offer-fesd-0000-1234-4321-1234567890ab",
      "advance_cents": 85000,
      "fee_cents": 15000,
      "payback_cents": 100000,
      "days": 90,
      "due_date": "2017-03-15"
    }
  ]
}
Possible Responses
200 - OKOffers available. 
202 - AcceptedNo offers available. 
400 - Bad RequestBad request 
403 - ForbiddenAccess denied 
404 - Not FoundInvoice with given identifier not found. 
418 - I'm a teapodI’m a teapot 
422 - Unprocessable EntityInvoice unprocessable 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Finance

The finance action starts the financing process for an invoice. A successful call to this endpoint will submit the passed invoice object to the financing process. With each request, a offer_id needs to be passed. To retreive the offer_id along with offer terms (payout amount, fee etc.) as well as the offer availability for a specific invoice before using this endpoint, the /offers endpoint must be utilized to retrieve available offers.

Finance POST

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • invoice_id string

    The unique identifier of the invoice that should be submitted to financing.

  • offer_id string

    The id of the offer the customer chose.

Definition
POST /customers/{customer_id}/finance
Example Request
{
  "invoice_id": "invoice-fesd-0000-1234-4321-1234567890ab",
  "offer_id": "offer-fesd-0000-1234-4321-1234567890ab"
}
Example Response
{
  "id": "finance-fesd-0000-1234-4321-1234567890ab",
  "resource_url": "http://www.finiata.com/invoice/fesd-0000-1234-4321-1234567890ab",
  "amount_cents": 1234,
  "due_date": "2017-01-30",
  "state": "in_progress",
  "offer_id": "offer-fesd-0000-1234-4321-1234567890ab"
}
Possible Responses
200 - OKFinancing application successfully submitted. 
400 - Bad RequestBad request 
403 - ForbiddenAccess denied 
404 - Not FoundInvoice with given identifier not found. 
418 - I'm a teapodI’m a teapot 
422 - Unprocessable EntityInvoice unprocessable 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Finance GET

Retrieves a deal including all of its details by the finance_id. By default this is our internal identifier, that has been passed to you with the creation of an deal.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • finance_id string

    Use this identifier to query a specific deal. By default the passed identifier refers to our internal id.

Definition
GET /customers/{customer_id}/finance/{finance_id}
Example Response
{
  "id": "finance-fesd-0000-1234-4321-1234567890ab",
  "resource_url": "http://www.finiata.com/invoice/fesd-0000-1234-4321-1234567890ab",
  "amount_cents": 1234,
  "due_date": "2017-01-30",
  "state": "in_progress",
  "offer_id": "offer-fesd-0000-1234-4321-1234567890ab"
}
Possible Responses
200 - OK 
404 - Not FoundDeal with given identifier not found. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Bank Accounts

Bank account and their history is primarily used in the risk assessment of the customer and his invoice recipient. A bank account transaction always relates to one bank account. In case a transaction is made between two accounts within the data-scope, this one transaction is modelled as two seperate (one receiving and one outgoing) transactions.

Bank Accounts POST

Use this endpoint to submit a bank account. A successful call repeats the validated bank account details and further provides the bankaccount_id a internal bank account identifier.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

Query Parameters
  • bank_name string

    The name of the bank.

  • bic string

    The BIC of the bank.

  • holder_name string

    The name of the bank account holder.

  • iban string

    The IBAN of the bank account.

  • balance_cents integer

    The current balance of the bank account in cents.

  • overdraft_limit_cents integer

    The overdraft limit of the bank account in cents.

Definition
POST /customers/{customer_id}/bankaccounts
Example Request
{
  "bank_name": "Some Banking Corp.",
  "bic": "HKJAS9876",
  "holder_name": "John Doe",
  "iban": "DE34983475983745987398",
  "balance_cents": 12342,
  "overdraft_limit_cents": 68165
}
Possible Responses
200 - OKBank account succesfully submitted. 
422 - Unprocessable EntityBank account details unprocessable - validation failed. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Bank Accounts PATCH

Use this endpoint to update an existing bank account. The bank account's id needs to be provided in the URI. By default this is our internal identifier, that was provided to you with the creation of the bank account. A successful call repeats the validated bank account details and further provides the bankaccount_id a internal bank account identifier.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • bankaccount_id string

    Use this identifier to query a specific bank account. By default the passed identifier refers to our internal id.

Query Parameters
  • bank_name string

    The name of the bank.

  • bic string

    The BIC of the bank.

  • holder_name string

    The name of the bank account holder.

  • iban string

    The IBAN of the bank account.

  • balance_cents integer

    The current balance of the bank account in cents.

  • overdraft_limit_cents integer

    The overdraft limit of the bank account in cents.

Definition
PATCH /customers/{customer_id}/bankaccounts/{bankaccount_id}
Example Request
{
  "query_by_external_id": true,
  "bank_name": "Some Banking Corp.",
  "bic": "HKJAS9876",
  "holder_name": "John Doe",
  "iban": "DE34983475983745987398",
  "balance_cents": 12342,
  "overdraft_limit_cents": 68165
}
Example Response
{
  "id": "ba-fesd-0000-1234-4321-1234567890ab",
  "bank_name": "Some Banking Corp.",
  "bic": "HKJAS9876",
  "holder_name": "John Doe",
  "iban": "DE34983475983745987398",
  "balance_cents": 12342,
  "overdraft_limit_cents": 68165
}
Possible Responses
200 - OKBank account succesfully updated. 
404 - Not FoundBank account with given identifier not found. 
422 - Unprocessable EntityBank account details unprocessable - validation failed. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Bank Accounts GET

Retrieves a bank account including all of its details by the bankaccount_id. By default this is our internal identifier, that was provided to you with the creation of the bank account.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • bankaccount_id string

    Use this identifier to query a specific bank account. By default the passed identifier refers to our internal id.

Definition
GET /customers/{customer_id}/bankaccounts/{bankaccount_id}
Example Response
{
  "id": "ba-fesd-0000-1234-4321-1234567890ab",
  "bank_name": "Some Banking Corp.",
  "bic": "HKJAS9876",
  "holder_name": "John Doe",
  "iban": "DE34983475983745987398",
  "balance_cents": 12342,
  "overdraft_limit_cents": 68165
}
Possible Responses
200 - OK 
404 - Not FoundBank account with given identifier not found. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Transactions

Bank account transactions which present the corresponding accounts transaction history.

Transactions POST

Use this endpoint to submit a transaction. A successful call repeats the validated transaction details and further provides the transaction_id, an internal transaction identifier.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • bankaccount_id string

    Use this identifier to query a specific bank account. By default the passed identifier refers to our internal id.

Query Parameters
  • reference string

    The name of the correspondent bank.

  • bank_name string

    The name of the bank.

  • bic string

    The BIC of the correspondent bank.

  • holder_name string

    The name of the correspondent bank account holder.

  • iban string

    The IBAN of the correspondent bank account.

  • amount_cents string

    The amount of the transaction in cents.

  • created_at string

    The date in ISO 8601 fromat, e.g. '2017-01-01', the transaction was booked.

Definition
POST /customers/{customer_id}/bankaccounts/{bankaccount_id}/transactions
Example Request
{
  "reference": "Invoice XYZ123",
  "bank_name": "Some Banking Corp.",
  "bic": "HKJAS9876",
  "holder_name": "John Doe",
  "iban": "DE34983475983745987398",
  "amount_cents": 616835,
  "created_at": "2017-01-01"
}
Possible Responses
200 - OKTransaction succesfully submitted. 
422 - Unprocessable EntityTransaction details unprocessable - validation failed. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Transactions GET

Retrieves a transaction including all of its details by our internal transaction_id.

URI Parameters
  • customer_id string

    Use this identifier to query a specific customer object. By default the passed identifier refers to our internal id, that has been provided to you with the creation of a customer.

  • bankaccount_id string

    Use this identifier to query a specific bank account. By default the passed identifier refers to our internal id.

  • transaction_id string

    Use this identifier to query a specific transaction. By default the passed identifier refers to our internal id.

Definition
GET /customers/{customer_id}/bankaccounts/{bankaccount_id}/transactions/{transaction_id}
Example Response
{
  "id": "ba-fesd-0000-1234-4321-1234567890ab",
  "reference": "Invoice XYZ123",
  "bank_name": "Some Banking Corp.",
  "bic": "HKJAS9876",
  "holder_name": "John Doe",
  "iban": "DE34983475983745987398",
  "amount_cents": 616835,
  "created_at": "2017-01-01"
}
Possible Responses
200 - OK 
404 - Not FoundTransaction with given identifier not found. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Configuration

The config endpoint exposes configuration options on the partner key level. For each partner key, configurations can be set. URLs are being validated on saving.

Webhook Configuration GET

Lists the current webhook configuration.

Definition
GET /config/webhooks
Example Response
{
  "invoice_webhook": "example.tld/some-uri/invoice",
  "customer_webhook": "example.tld/some-uri/customer"
}
Possible Responses
200 - OK 
400 - Bad RequestBad request 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Webhook Configuration POST

Save a webhook URL configuration.

Query Parameters
  • customer_webhook string

    Sets the customer webhook URL

  • invoice_webhook string

    Sets the invoice webhook URL

Definition
POST /config/webhooks
Example Request
{
  "invoice_webhook": "http://example.tld/some-uri/invoice",
  "customer_webhook": "http://example.tld/some-uri/customer"
}

Webhooks

Definition of webhook endpoints on partner side!

Invoice Webhook POST

Used for signalling state changes of an invoice.

URI Parameters
  • invoice_webhook string
Query Parameters
  • auth_token string

    SHA256 hashed version of your api key

  • customer_id string

    Unique identifier of the customer.

  • invoice_id string

    Unique identifier of the invoice.

  • state string

    The state, the invoice has moved into. Can be any of ['draft', 'incomplete', 'in_progress', 'offer', 'confirmation', 'identification', 'paid_out', 'partial_payback', 'overdue', 'collection', 'compelete', 'rejected']

  • message string

    A state-change can include a unstructured message describing, what happened.

Definition
POST /webhooks/{invoice_webhook}
Example Request
{
  "auth_token": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "customer_id": "i12345",
  "invoice_id": "c99876",
  "state": "rejected",
  "message": "Invoice already overdue."
}
Possible Responses
200 - OKMessage is received successfully. 
400 - Bad RequestBad request. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

Customer Webhook

Used for signalling status update change of a customer.

Customer Webhook POST

The customer webhook will be triggered to update your system about the customers status. Particularily, the webhook will be called with a status of onboarding_complete as soon as the customer is completely onboarded.

URI Parameters
  • customer_webhook string
Query Parameters
  • auth_token string

    SHA256 hashed version of your api key

  • customer_id string

    The unique identifier of the customer.

  • event_id string

    A string identifying the event.

Definition
POST /webhooks/{customer_webhook}
Example Request
{
  "auth_token": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "customer_id": "i12345",
  "event_id": "onboarding_complete"
}
Possible Responses
200 - OKMessage is received successfully. 
400 - Bad RequestBad request. 
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)