Introduction

Welcome to the Novicap early payments API. You can use our API to synchronize suppliers, debtors, and invoices to our platform, and manage their financing.

Please contact [email protected] if you have any questions.

Authentication

To authorize while using a GET endpoint:

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/suppliers?product_id=123"

To authorize while using a POST endpoint, you have more options, since a JSON payload is accepted. Either of these is valid:

curl --header "Authorization: Bearer abcd" --header "Content-Type: application/json" --data '{"payment_adjustments": []}' \
"https://api.novicap.com/v1/dynamic_discounting/payment_adjustments?product_id=123"

curl --header "Content-Type: application/json" --data '{
  "api_key": "abcd",
  "product_id": 123,
  "payment_adjustments": []
}' \
"https://api.novicap.com/v1/dynamic_discounting/payment_adjustments"

where abcd should be replaced with your API key, and 123 with your product ID. We advise using a JSON payload instead of putting data into the URL, as it is required for more some endpoints that accept things like arrays and objects.

We use an API key to authenticate which can be found by logging into your account at novicap.com and generating it under your user profile. All API hits will be associated with your user and an indefinite audit log is accessible from your account.

The API key should be included in all requests to the server either as a HTTP request parameter named api_key, inside a JSON payload with key api_key, or inside an Authorization: Bearer HTTP request header.

All API requests target a particular product inside your account, such as factoring or dynamic discounting. Each product has an ID which you can find inside the platform near the API key. The product ID should be included in all requests as a HTTP request parameter named product_id or inside a JSON payload with key product_id.

OAuth 2.0 authentication is available on request. The exact implementation will depend on your authentication provider and workflow.

Permissions

Available endpoints depend on the configuration of your account. If you receive a 403 error while trying to access a specific endpoint, please contact [email protected] to request access.

Identifying companies

Our system uses a unique ID for each company (supplier or debtor) composed of the ISO 2-letter country code and an ID depending on the country. It is required for us to correctly identify the legal entity we're dealing with.

In the United Kingdom, this is defined as GB and the 8 digit Companies House number. For example, Tesco PLC has a country code of GB and an ID of 00445790.

In Spain, this is defined as ES and the CIF code. For example, Mercadona SA has a country code of ES and an ID of A46103834.

Dynamic discounting

Add suppliers

curl --header "Authorization: Bearer abcd" --header "Content-Type: application/json" --data '{
  "suppliers": [
    {
      "country_code": "GB",
      "supplier_id": "00445790",
      "supplier_name": "Tesco PLC",
      "contact_first_name": "John",
      "contact_last_name": "Smith",
      "contact_email": "[email protected]",
      "contact_phone": "+44724565898",
      "apr": 10,
      "custom_supplier_data": { "internal_id": "supplier-001", "tags": ["batch 1"] }
    }
  ]
}' \
"https://api.novicap.com/v1/dynamic_discounting/suppliers?product_id=123"

The above command returns a empty JSON payload with the 201 CREATED status.

This endpoint adds suppliers to your dynamic discounting product. You must add suppliers before you add invoices for those suppliers.

The company will receive an onboarding email chain, and we may reach out to the company by phone to assist in onboarding.

If your account has more than one legal entity, you must include a debtor_id along with every supplier, representing the entity which will pay invoices to that supplier.

HTTP Request

POST https://api.novicap.com/v1/dynamic_discounting/suppliers

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Schema for POST /v1/dynamic_discounting/suppliers",
  "type": "object",
  "required": ["suppliers"],
  "properties": {
    "suppliers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["supplier_id", "supplier_name", "contact_email"],
        "properties": {
          "debtor_id": {"type": "string"},
          "country_code": {"type": "string"},
          "supplier_id": {"type": "string"},
          "supplier_name": {"type": "string"},
          "contact_first_name": {"type": "string"},
          "contact_last_name": {"type": "string"},
          "contact_email": {"type": "string"},
          "contact_phone": {"type": ["string", "number"]},
          "apr": {"type": "number"},
          "fixed_fee_percentage": {"type": "number"},
          "early_payment_cutoff_in_days": {"type": "integer"},
          "iban": {"type": "string"},
          "custom_supplier_data": {"type": "object"}
        }
      }
    }
  }
}

Suppliers

Response

A successful response has a 201 Created HTTP status code.

Retrieve suppliers

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/suppliers?product_id=123"

The above command returns an array of Supplier objects in the JSON payload with the 200 OK status.

This endpoint returns all the suppliers in your dynamic discounting product.

HTTP Request

GET https://api.novicap.com/v1/dynamic_discounting/suppliers

Response

A successful response has a 200 OK HTTP status code along with an array of supplier objects described above.

Add invoices

curl --header "Authorization: Bearer abcd" --header "Content-Type: application/json" --data '{
  "invoices": [
    {
      "supplier_id": "00445790",
      "reference": "A1234",
      "amount": 1000,
      "due_at": "2021-10-30",
      "custom_invoice_data": { "internal_id": "inv-001", "tags": ["batch 1"] }
    }
  ]
}' \
"https://api.novicap.com/v1/dynamic_discounting/invoices?product_id=123"

The above command returns a empty JSON payload with the 201 CREATED status.

This endpoint adds invoices to your dynamic discounting product. You must add suppliers before you add invoices for those suppliers.

The company will receive an onboarding email chain, and we may reach out to the company by phone to assist in onboarding.

If your account has more than one legal entity, you must include a debtor_id along with every supplier, representing the entity which will pay invoices to that supplier.

If an invoice already exists under the product with the same supplier and reference, and the invoice is not yet part of a payment instruction, we attempt to update it. If the supplier has already accepted early payment and the update changes the amount, due_at, or invoice_adjustments, we will cancel acceptance and ask the supplier to accept the new terms instead.

HTTP Request

POST https://api.novicap.com/v1/dynamic_discounting/invoices

Parameters

The params for this endpoint should match this JSON schema:

{
  "description": "Invoices create endpoint json schema",
  "type": "object",
  "required": ["invoices"],
  "properties": {
    "invoices": {
      "type":"array",
      "items": {
        "type": "object",
        "required": ["supplier_id", "reference", "amount", "due_at"],
        "properties": {
          "debtor_id": { "type": "string" },
          "supplier_id": { "type": "string" },
          "reference": { "type": "string" },
          "amount": { "type": "number" },
          "due_at": { "type": "string" },
          "custom_invoice_data": {"type": "object"},
          "invoice_adjustments": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["adjustment_id", "adjustment"],
              "properties": {
                "adjustment_id": { "type": "string" },
                "adjustment": { "type": "number" }
              }
            }
          }
        }
      }
    }
  }
}

Invoice (create)

Invoice adjustment

You may have pre-existing credit notes that you want to apply to an invoice. These apply before we calculate a discount based on the APR. The supplier will be shown these adjustments inside the platform.

Response

A successful response has a 201 Created HTTP status code.

Retrieve invoices

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/invoices?product_id=123"

The above command returns an array of Invoice objects in the JSON payload with the 200 OK status.

This endpoint returns all the invoices registered in your product.

HTTP Request

GET https://api.novicap.com/v1/dynamic_discounting/invoices

Response

A successful response has a 200 OK HTTP status code along with an array of invoice objects.

Invoice (index)

Each invoice object has the following schema:

Rectified invoice

Each rectified invoice object has the following schema:

Delete invoice

curl --header "Authorization: Bearer abcd" --request DELETE "https://api.novicap.com/v1/dynamic_discounting/invoices/DDI-ABCD?product_id=123"

The above command returns a empty JSON payload with the 200 ACCEPTED status.

This endpoint permanently deletes the invoice. This cannot be undone.

The URL must contain a valid transaction ID, matching one returned from GET /v1/dynamic_discounting/invoices. The transaction ID is not the same as the reference of the invoice submitted by you.

The invoice cannot be deleted if it is already part of a payment instruction. If the supplier has already accepted early payment, we will notify them that the invoice is no longer eligible and that they will not receive it.

HTTP Request

DELETE https://api.novicap.com/v1/dynamic_discounting/invoices/:transaction_id

Response

A successful response has a 200 OK HTTP status code.

Create payment instruction

curl --header "Authorization: Bearer abcd" --header "Content-Type: application/json" --data '{}' \
"https://api.novicap.com/v1/dynamic_discounting/payment_instructions?product_id=123"

The above command returns a JSON payload with the 201 CREATED status.

This endpoint creates a payment instruction for all the invoices accepted by the supplier which hasn't been included in an instruction already.

If your account has more than one legal entity, you must include a debtor_id, representing the entity which will pay invoices to suppliers.

HTTP Request

POST https://api.novicap.com/v1/dynamic_discounting/payment_instructions

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Payment instructions create endpoint json schema",
  "type": "object",
  "properties": {
    "debtor_id": { "type": "string" }
  }
}

Response

A successful response has a 201 Created HTTP status code along with a payment instruction object described below.

Retrieve payment instructions

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/payment_instructions?product_id=123"

The above command returns a JSON payload with the 200 OK status.

This endpoint returns all the payments instructions associated with the product.

HTTP Request

GET https://api.novicap.com/v1/dynamic_discounting/payment_instructions

Payment instructions

Payment instruction

Payment

Response

A successful response has a 200 OK HTTP status code along with the list of payment instructions and the included invoices.

Create payment adjustment

curl --header "Authorization: Bearer abcd" --header "Content-Type: application/json" --data '{
  "payment_adjustments": [
    {
      "supplier_id": "00445790",
      "reference": "ADJ-001",
      "amount": -100
    }
  ]
}' \
"https://api.novicap.com/v1/dynamic_discounting/payment_adjustments?product_id=123"

The above command returns a JSON payload with the 201 CREATED status.

This endpoint creates an adjustment to the next payment to a supplier. It can be used to collect outstanding credit notes from the next payment you make, instead of attaching adjustments to individual invoices using invoice adjustments.

If your account has more than one legal entity, you must include a debtor_id. The next time that entity (but not others) creates a payment instruction to the given supplier, the payment adjustment will be applied.

HTTP Request

POST https://api.novicap.com/v1/dynamic_discounting/payment_adjustments

Parameters

The params for this endpoint should match this JSON schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "description": "Payment adjustment create endpoint json schema",
  "type": "object",
  "required": ["payment_adjustments"],
  "properties": {
    "payment_adjustments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["supplier_id", "reference", "amount"],
        "properties": {
          "debtor_id": { "type": "string" },
          "supplier_id": { "type": "string" },
          "reference": { "type": "string" },
          "amount": { "type": "number" },
          "custom_payment_adjustment_data": { "type": "object" }
        }
      }
    }
  }
}

 Payment adjustment (create)

Response

A successful response has a 201 Created HTTP status code.

Retrieve payment adjustments

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/payment_adjustments?product_id=123"

The above command returns a JSON payload with the 200 OK status.

This endpoint returns all the payments adjustments associated with the product.

HTTP Request

GET https://api.novicap.com/v1/dynamic_discounting/payment_adjustments

Response

A successful response has a 200 OK HTTP status code along with the list of payment adjustments.

Payment adjustment (index)

Delete payment adjustment

curl --header "Authorization: Bearer abcd" --request DELETE "https://api.novicap.com/v1/dynamic_discounting/payment_adjustments/DDPI-ABCD?product_id=123"

The above command returns a empty JSON payload with the 200 ACCEPTED status.

This endpoint permanently deletes the payment adjustment. This cannot be undone.

The URL must contain a valid transaction ID, matching one returned from GET /v1/dynamic_discounting/payment_adjustments. The transaction ID is not the same as the reference of the payment adjustment submitted by you.

The payment adjustment cannot be deleted if it is already part of a payment instruction.

HTTP Request

DELETE https://api.novicap.com/v1/dynamic_discounting/payment_adjustments/:transaction_id

Response

A successful response has a 200 OK HTTP status code.

Confirming standard

Add confirming invoices

curl --header "Authorization: Bearer abcd" --header "Content-Type: application/json" --data '{
  "invoices": [
    {
      "supplier_id": "00445790",
      "reference": "A1234",
      "amount": 1000,
      "issued_at": "2024-05-30",
      "due_at": "2024-10-30",
    }
  ]
}' \
"https://api.novicap.com/v1/confirming_standard/invoices?product_id=123"

The above command returns a empty JSON payload with the 201 CREATED status.

This endpoint adds invoices to your confirming standard product. If the supplier doesn't exist you must pass the supplier_name and contact_email to create them in the same request.

The company will receive an onboarding email chain, and we may reach out to the company by phone to assist in onboarding.

If your account has more than one legal entity, you must include a debtor_id along with every supplier, representing the entity which will pay invoices to that supplier.

HTTP Request

POST https://api.novicap.com/v1/confirming_standard/invoices

Parameters

The params for this endpoint should match this JSON schema:

{
  "description": "Invoices create endpoint json schema",
  "type": "object",
  "required": ["invoices"],
  "properties": {
    "invoices": {
      "type":"array",
      "items": {
        "type": "object",
        "required": ["supplier_id", "reference", "amount", "issued_at", "due_at"],
        "properties": {
          "debtor_id": { "type": "string" },
          "country_code": { "type": "string" },
          "supplier_id": { "type": "string" },
          "supplier_name": { "type": "string" },
          "contact_first_name": { "type": "string" },
          "contact_last_name": { "type": "string" },
          "contact_email": { "type": "string" },
          "contact_phone": { "type": "string" },
          "iban": { "type": "string" },
          "bic": { "type": "string" },
          "reference": { "type": "string" },
          "amount": { "type": "number" },
          "issued_at": { "type": "string" },
          "due_at": { "type": "string" },
          "self_confirming": { "type": "boolean" }
        }
      }
    }
  }
}

Confirming invoice (create)

Response

A successful response has a 201 Created HTTP status code.

Retrieve confirming invoices

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/confirming_standard/invoices?product_id=123"

The above command returns an array of Invoice objects in the JSON payload with the 200 OK status.

This endpoint returns all the invoices registered in your product.

HTTP Request

GET https://api.novicap.com/v1/confirming_standard/invoices

Response

A successful response has a 200 OK HTTP status code along with an array of invoice objects.

Confirming invoice (index)

Each invoice object has the following schema:

Delete confirming invoice

curl --header "Authorization: Bearer abcd" --request DELETE "https://api.novicap.com/v1/confirming_standard/invoices/I-ABCD?product_id=123"

The above command returns a empty JSON payload with the 200 ACCEPTED status.

This endpoint permanently deletes the invoice. This cannot be undone.

The URL must contain a valid transaction ID, matching one returned from GET /v1/confirming_standard/invoices. The transaction ID is not the same as the reference of the invoice submitted by you.

The invoice cannot be deleted if it is already part of a payment instruction or if it has been already paid.

HTTP Request

DELETE https://api.novicap.com/v1/confirming_standard/invoices/:transaction_id

Response

A successful response has a 200 OK HTTP status code.

Retrieve confirming payment instructions

curl --header "Authorization: Bearer abcd" "https://api.novicap.com/v1/confirming_standard/payment_instructions?product_id=123"

The above command returns a JSON payload with the 200 OK status.

This endpoint returns all the payments instructions associated with the product.

HTTP Request

GET https://api.novicap.com/v1/confirming_standard/payment_instructions

Confirming payment instructions

Confirming payment instruction

Confirming payment

Response

A successful response has a 200 OK HTTP status code along with the list of payment instructions and the included invoices.

Errors

Any HTTP request may fail with one of the following errors.