NAV
shell

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"}
        }
      }
    }
  }
}
Parameter Type Required Format Description
suppliers Array Array of supplier objects A list of suppliers you want to add

Suppliers

Parameter Type Required Format Default value Description
debtor_id String If your account contains more than one legal entity, this is the ID of the entity that pays invoices to this supplier
country_code String ISO 3166 alpha-2 ES The country code of the supplier
supplier_id String Depends on country code The ID of the supplier (see identifying companies)
supplier_name String The name of the supplier
contact_first_name String The first name of the supplier contact
contact_last_name String The last name of the supplier contact
contact_email String The email of the supplier contact
contact_phone String/Number The full phone number of the supplier contact, including country code
apr Number Percentage points Configured per product The APR your want this supplier to pay in percentage points e.g. 10% -> 10
fixed_fee_percentage Number Percentage points Configured per product The fixed fee, as a percentage of the face value of the invoice, you want the supplier to pay, in percentage points e.g. 0.5% -> 0.5
early_payment_cutoff_in_days Number 10 This number of days before the due date, we stop allowing the supplier to accept financing
iban String IBAN The IBAN code of the bank account you pay to when making payments to the supplier
custom_supplier_data Object Any valid JSON, maximum of 8192 characters [] Any data you want to associate with this supplier

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" }
              }
            }
          }
        }
      }
    }
  }
}
Parameter Type Required Format Description
invoices Array Array of invoice objects A list of invoices to create

Invoice (create)

Parameter Type Required Format Default value Description
debtor_id String If your account contains more than one legal entity, this is the ID of the entity that pays invoices to this supplier
supplier_id String Depends on country code The ID of the supplier (see identifying companies)
reference String The reference of the invoice
amount String The amount of the invoice
due_at String ISO 8601 The date on which the invoice is due
custom_invoice_data Object Any valid JSON, maximum of 8192 characters {} Any data you want to associate with this invoice
invoice_adjustments Array Array of adjustment objects [] A list of changes to the invoice amount that should be applied before the discount

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.

Parameter Type Required Format Default value Description
adjustment_id String A reference which we show to the supplier
adjustment Number The adjustment to the amount of the invoice that you want to make. For a credit note, this should be negative.

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.

Parameter Type Format Description
invoices Array Array of invoice objects A list of all invoices in the product

Invoice (index)

Each invoice object has the following schema:

Parameter Type Format Description
supplier_id String Depends on country The ID of the supplier (see identifying companies)
debtor_id String Depends on country The ID of the debtor (see identifying companies)
reference String The reference you gave us - unique for each pair of debtor and supplier
transaction_id String A unique reference for this invoice in our system
amount Number The amount (face value) of the invoice
discount Number The total discount that the supplier agreed to in return for early payment
facilitator_fee Number The amount we will charge you for processing this invoice
accepted_at String ISO 8601 The date the supplier (most recently) accepted early payment of this invoice
due_at String ISO 8601 The date this invoice is due
management_status String An internal invoice status that may help you track how the invoice is doing
rectified_invoice_url String URL A link to the rectified invoice PDF generated by the supplier. Expires after 1 week.
rectified_invoice_data Object A rectified invoice object Data from the rectified invoice PDF
payment_instruction_id String The payment instruction that this invoice is included in
custom_invoice_data Object Any valid JSON The custom invoice data you gave us
custom_supplier_data Object Any valid JSON The custom supplier data you gave us
invoice_adjustments Array Array of adjustment objects The pre-discount ajustments you gave us

Rectified invoice

Each rectified invoice object has the following schema:

Parameter Type Format Description
reference String The reference of the rectified invoice, given to us by the supplier
vat_percent Number Percentage points The VAT percentage on the rectified invoice PDF
vat_base Number The base amount to charge VAT on
vat_amount Number The amount of VAT
issued_at String ISO 8601 The date on the rectified invoice PDF

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" }
  }
}
Parameter Type Required Format Description
debtor_id Number The ID of the entity, if your account has more then one legal entity

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

Parameter Type Format Description
payment_instructions Array Array of payment instruction objects List of payment instructions in your account

Payment instruction

Parameter Type Format Description
payment_instruction_id String A unique ID for this payment instruction
invoices Array Array of invoice objects A list of invoices associated with this payment instruction
payments Array Array of payment objects A list of payments to make, one per supplier

Payment

Parameter Type Format Description
supplier_name String Name of the supplier to pay
supplier_id String Depends on country code The ID of the supplier to pay (see identifying companies)
debtor_name String Name of the legal entity that should make the payment, which matters if you have more than one in your account
debtor_id String Depends on country code The ID of the legal entity that should make the payment (see identifying companies)
amount Number The amount you should pay the supplier
iban String IBAN The bank account you should pay into (if you give it to us)
references String Seperated by ', ' (comma then space) A list of invoice references included in this 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" }
        }
      }
    }
  }
}
Parameter Type Required Format Description
payment_adjustments Array Array of payment adjustment objects The payment adjustments you want to add or update

 Payment adjustment (create)

Parameter Type Required Format Description
debtor_id String If your account contains more than one legal entity, this is the ID of the entity that has the payment adjustment
supplier_id String Depends on country code The ID of the supplier (see identifying companies)
reference String The reference of the payment adjustment that will be shown to the supplier
amount Number The amount of the payment adjustment. For credit notes, this should be negative.
custom_payment_adjustment_data Object Any valid JSON, maximum of 8192 characters Any data you want to associate with this payment adjustment

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.

Parameter Type Format Description
payment_adjustments Array Array of payment adjustment objects List of payment adjustments in your account

Payment adjustment (index)

Parameter Type Description
debtor_id String If your account contains more than one legal entity, this is the ID of the entity that has the payment adjustment
supplier_id String The ID of the supplier (see identifying companies)
reference String The reference of the payment adjustment that is shown to the supplier
transaction_id String A unique internal ID used for the destroy endpoint
amount Number The amount of the payment adjustment. For credit notes, this should be negative.
custom_payment_adjustment_data Object Any data you gave us to associate with this payment adjustment
payment_instruction_id String The ID of the payment instruction that this adjustment was applied to, if it has been applied

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.

Errors

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

Error Code Meaning
400 Bad Request -- The formatting of the request is not correct
401 Unauthorized -- Your API key is not recognised
403 Forbidden -- Your API key is recognised and the URL is correct, but you do not have permission to perform that action
404 Not Found -- The URL is not correct
500 Internal Server Error -- We had an unexpected problem on our side - contact support or try again later
502 Bad Gateway -- Something went wrong between you and our servers - contact support or try again later
503 Service Unavailable -- We're under unusually high load and can't respond to that request at the moment - contact support or try again later
504 Gateway Timeout -- We're under unusually high load and can't respond to that request at the moment - contact support or try again later