Notification API API Reference

API that can be implemented by the integrator, the issuer or the payment requestor to receive notifications

API Endpoint
http://localhost:8180/
Contact: support@digiteal.eu
Version: 1.3

Paths

payment-notification-controller

Company change

POST /v1/api/payment-notification/company
CompanyNotification

companyNotification

Request Content-Types: application/json
Request Example
{
  "canReceiveFunds": false,
  "canSendFunds": false,
  "changeType": "CREATED",
  "comment": "A very informative comment",
  "executionTimestamp": "2019-05-31 17:23:45",
  "ibans": [
    "string"
  ],
  "id": 12,
  "integratorVAT": "BE0000000196",
  "name": "Company X",
  "nationalIdentifier": "BE:VAT:BE0000000097",
  "paymentMethods": [
    "string"
  ],
  "trustedPaymentIntegratorVAT": "BE0000000295",
  "vat": "BE0000000097"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Auto pay configuration creation or change

POST /v1/api/payment-notification/config-change
AutoPayConfiguration

autoPayConfiguration

Request Content-Types: application/json
Request Example
{
  "changeType": "CREATE",
  "clientID": "Client1234",
  "currency": "EUR",
  "executionTimestamp": "2019-05-31 17:23:45",
  "maxAmount": 10000,
  "paymentDate": "ONE_WEEK_BEFORE_DUE_DATE",
  "periodicity": "MONTH",
  "requesterID": "12",
  "requesterIdentificationNumber": "BE:VAT:BE0000000097",
  "requesterVAT": "BE0000000097"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Payment confirmation

POST /v1/api/payment-notification/confirmation
PaymentConfirmationNotification

paymentConfirmationNotification

Request Content-Types: application/json
Request Example
{
  "originBankAccount": "BE41816373160590",
  "paidAmountInCents": 1234,
  "paymentConfirmationDate": "2019-05-31",
  "paymentID": "e529f8b4790f11e7b5a5be2e44b06b52"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Customer change

POST /v1/api/payment-notification/customer
CustomerNotification

customerNotification

Request Content-Types: application/json
Request Example
{
  "changeType": "OPTIN",
  "channel": "DIGITEAL",
  "creditorId": 12,
  "creditorName": "Company X",
  "creditorNationalIdentifier": "BE:VAT:BE0000000097",
  "creditorVAT": "BE0000000097",
  "customerInternalId": "Customer1234",
  "email": "john.doe@me.com",
  "executionTimestamp": "2019-05-31 17:23:45",
  "integratorVAT": "BE0000000196",
  "trustedPaymentIntegratorVAT": "BE0000000295"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Payment error occured

POST /v1/api/payment-notification/error
paymentID: string
in query

The unique identifier of the payment known by the requester

errorType: string TECHNICAL_ERROR, SECURITY_ISSUE, CANCELED
in query

The type of error that occured. Possible errors are technical error, client canceled payment during the flow, a security issue occured (pin code blocked, ...)

message: string
in query

Detailed message concerning the error

200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Invoice change

POST /v1/api/payment-notification/invoice
InvoiceNotification

invoiceNotification

Request Content-Types: application/json
Request Example
{
  "amountInCents": 1234,
  "changeType": "PAID",
  "comment": "A comment from Digiteal",
  "creditNoteAmountInCents": 123,
  "creditNoteUUID": "a529f8b4790f11e7b5a5be2e44b06b54",
  "currency": "EUR",
  "customerEmail": "john.doe@me.com",
  "customerFirstName": "John",
  "customerIban": "BE41816373160590",
  "customerInternalId": "Customer1234",
  "customerName": "Doe",
  "customerVAT": "BE0000000196",
  "documentExtension": "pdr",
  "documentFileName": "Invoice1234.pdf",
  "documentUUID": "f529f8b4790f11e7b5a5be2e44b06b53",
  "executionTimestamp": "2019-05-31 17:23:45",
  "internalId": "Invoice1234",
  "issuerId": 12,
  "issuerName": "Company X",
  "issuerNationalIdentifier": "BE:VAT:BE0000000097",
  "issuerVAT": "BE0000000097",
  "status": "PAID",
  "uuid": "e529f8b4790f11e7b5a5be2e44b06b52"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

PEPPOL notification

POST /v1/api/payment-notification/peppol
PeppolNotification

peppolNotification

Request Content-Types: application/json
Request Example
{
  "changeType": "PEPPOL_INVOICE_RECEIVED",
  "executionTimestamp": "2019-05-31 17:23:45",
  "integratorVAT": "BE0000000097",
  "peppolFileContent": "Encoded in Base64",
  "recipientPeppolIdentifier": "9956:0630675588"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Person change

POST /v1/api/payment-notification/person
PersonNotification

personNotification

Request Content-Types: application/json
Request Example
{
  "changeType": "CREATED",
  "comment": "A very informative comment",
  "executionTimestamp": "2019-05-31 17:23:45",
  "firstName": "John",
  "id": 12,
  "integratorVAT": "BE0000000097",
  "lastName": "Doe",
  "trustedPaymentIntegratorVAT": "BE0000000196"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*
payment-notification-controller

Transfer of funds

POST /v1/api/payment-notification/transfer-of-funds
TransferOfFundsNotification

transferOfFundsNotification

Request Content-Types: application/json
Request Example
{
  "bankTransactionID": "e529f8b4790f11e7b5a5be2e44b06b52",
  "errorCode": "SOME_CODE",
  "errorMessage": "An error message",
  "executionTimestamp": "2019-05-31 17:23:45",
  "invoiceUUID": "a529f8b4790f11e7b5a5be2e44b06b54",
  "originBankAccount": "BE41816373160590",
  "originCompanyName": "MyCompany",
  "originFirstName": "John",
  "originLastName": "Doe",
  "originVATNumber": "BE0000000196",
  "parentBankTransactionID": "b229f8b4790f11e7b5a5be2e44b06b55",
  "paymentMethod": "VISA",
  "paymentRequestInformation": {
    "amountInCents": 1234,
    "clientID": "34",
    "creditorReference": "000600232562",
    "currency": "EUR",
    "destinationBankAccount": "BE41816373160590",
    "paymentID": "e529f8b4790f11e7b5a5be2e44b06b52",
    "paymentInternalId": "Payment1234",
    "paymentRequestDate": "2019-05-31",
    "paymentRequestDuedate": "2019-06-15",
    "purpose": "GDDS",
    "remittanceInfo": "Invoice1234",
    "requestorID": 12,
    "requestorNationalIdentifier": "BE:VAT:BE0000000097",
    "requestorVAT": "BE0000000097"
  },
  "paymentStatus": "INITIATED",
  "targetBankAccount": "BE17999000004821",
  "transferID": "f529f8b4790f11e7b5a5be2e44b06b53"
}
200 OK

Success

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

500 Internal Server Error

Internal server error occured

Response Content-Types: */*

Schema Definitions

InvoiceNotification: object

Model representing invoice notification

amountInCents: integer (int64)

Total amount of the invoice expressed in cents

changeType: string PUBLISHED, READ, PAID, COMMENTED, UNPAID, INVOICE_DOCUMENT_ADDED, CREDIT_NOTE_PUBLISHED, CREDIT_NOTE_DOCUMENT_ADDED

Type of change to the invoice

comment: string

Comment of the customer on the invoice

creditNoteAmountInCents: integer (int64)

the amount of the credit note in cents

creditNoteUUID: string

UUID of the credit note

currency: string

Currency of the payment to be performed linked to this invoice

customerEmail: string

Customer email

customerFirstName: string

First name of the customer

customerIban: string

Customer IBAN

customerInternalId: string

Customer internal Id (as definied by the issuer)

customerName: string

Name of the customer (last name for an individual)

customerVAT: string

VAT number of the customer

documentExtension: string

Extension of the document attached to the invoice

documentFileName: string

File name of the document attached to the invoice

documentUUID: string

UUID of the document attached to the invoice

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

internalId: string

Identifier of the invoice as provided by the issuer

issuerId: integer (int64)

Identifier of the issuer (as defined by Digiteal)

issuerName: string

Name of the issuer

issuerNationalIdentifier: string

National identifier of the issuer

issuerVAT: string

VAT number of the issuer

status: string

Status of the invoice

uuid: string

UUID of the invoice

Example
{
  "amountInCents": 1234,
  "changeType": "PAID",
  "comment": "A comment from Digiteal",
  "creditNoteAmountInCents": 123,
  "creditNoteUUID": "a529f8b4790f11e7b5a5be2e44b06b54",
  "currency": "EUR",
  "customerEmail": "john.doe@me.com",
  "customerFirstName": "John",
  "customerIban": "BE41816373160590",
  "customerInternalId": "Customer1234",
  "customerName": "Doe",
  "customerVAT": "BE0000000196",
  "documentExtension": "pdr",
  "documentFileName": "Invoice1234.pdf",
  "documentUUID": "f529f8b4790f11e7b5a5be2e44b06b53",
  "executionTimestamp": "2019-05-31 17:23:45",
  "internalId": "Invoice1234",
  "issuerId": 12,
  "issuerName": "Company X",
  "issuerNationalIdentifier": "BE:VAT:BE0000000097",
  "issuerVAT": "BE0000000097",
  "status": "PAID",
  "uuid": "e529f8b4790f11e7b5a5be2e44b06b52"
}

TransferOfFundsNotification: object

Model representing transfer of fund notification

bankTransactionID: string

The unique identifier of the payment known by the requester

errorCode: string

Error code indication

errorMessage: string

Detailed error message

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

invoiceUUID: string

UUID of the invoice

originBankAccount: string

The bank account of the ultimate debtor

originCompanyName: string

The name of the ultimate debtor company (if it is a company)

originFirstName: string

The first name of the ultimate debtor or its contact person (if it is a company)

originLastName: string

The last name of the ultimate debtor or its contact person (if it is a company)

originVATNumber: string

The VAT number of the ultimate debtor (if it is a company)

parentBankTransactionID: string

The unique identifier of the payment known by the requester

paymentMethod: string STANDARD, DIRECT, BANCONTACT, IDEAL, VISA, INTERNAL, MASTERCARD, CARTE_BLEUE, MAESTRO, PAYCONIQ, SCT

Possible values are STANDARD, DIRECT, BANCONTACT, IDEAL, VISA, MASTERCARD, CARTE_BLEUE

paymentRequestInformation: PaymentRequestInformation

Represents the basic invoice information

paymentStatus: string INITIATED, INITIATION_ERROR, WITHDRAWAL_ERROR, WITHDRAWAL_SUCCESS, REIMBURSMENT_FROM_DIGITEAL, REIMBURSMENT_FROM_REQUESTOR, TRANSFERRED, TRANSFER_PAYMENT_RECEIVED, TRANSFER_PAYMENT_STARTED, TRANSFER_PAYMENT_COMPLETED, TRANSFER_REIMBURSEMENT_STARTED, TRANSFER_REIMBURSEMENT_COMPLETED

The status of the payment

targetBankAccount: string

The bank account of the ultimate creditor

transferID: string

The unique identifier of the trusted transfer known by the requester

Example
{
  "bankTransactionID": "e529f8b4790f11e7b5a5be2e44b06b52",
  "errorCode": "SOME_CODE",
  "errorMessage": "An error message",
  "executionTimestamp": "2019-05-31 17:23:45",
  "invoiceUUID": "a529f8b4790f11e7b5a5be2e44b06b54",
  "originBankAccount": "BE41816373160590",
  "originCompanyName": "MyCompany",
  "originFirstName": "John",
  "originLastName": "Doe",
  "originVATNumber": "BE0000000196",
  "parentBankTransactionID": "b229f8b4790f11e7b5a5be2e44b06b55",
  "paymentMethod": "VISA",
  "paymentRequestInformation": {
    "amountInCents": 1234,
    "clientID": "34",
    "creditorReference": "000600232562",
    "currency": "EUR",
    "destinationBankAccount": "BE41816373160590",
    "paymentID": "e529f8b4790f11e7b5a5be2e44b06b52",
    "paymentInternalId": "Payment1234",
    "paymentRequestDate": "2019-05-31",
    "paymentRequestDuedate": "2019-06-15",
    "purpose": "GDDS",
    "remittanceInfo": "Invoice1234",
    "requestorID": 12,
    "requestorNationalIdentifier": "BE:VAT:BE0000000097",
    "requestorVAT": "BE0000000097"
  },
  "paymentStatus": "INITIATED",
  "targetBankAccount": "BE17999000004821",
  "transferID": "f529f8b4790f11e7b5a5be2e44b06b53"
}

CompanyNotification: object

Model representing a company notification

canReceiveFunds: boolean

The company can receive funds. It can do this once all the conditions to send funds are met, that the company has a paying profile and that there is at least one activated payment method.

canSendFunds: boolean

The company can send funds. It can do this once the company has been validated and at least one IBAN is validated too.

changeType: string CREATED, REJECTED, VALIDATED, UPDATED, PUT_ON_HOLD, CHANGED_INTEGRATOR, CHANGED_TRUSTED_PAYMENT_INTEGRATOR, DELETED

Describes the change on the company

comment: string

A comment linked to this notification.

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

ibans: string[]

IBANs of the validated bank accounts associated to the company.

string
id: integer (int64)

The Digiteal ID of the company

integratorVAT: string

The VAT number of the integrator

name: string

The name of the company

nationalIdentifier: string

The identification number of the company composed by an optional country, the scheme identifier and the identifier.

paymentMethods: string[]

Activated payment methods

string STANDARD, DIRECT, BANCONTACT, IDEAL, VISA, INTERNAL, MASTERCARD, CARTE_BLEUE, MAESTRO, PAYCONIQ, SCT
trustedPaymentIntegratorVAT: string

The VAT number of the trusted payment integrator

vat: string

The VAT number of the company

Example
{
  "canReceiveFunds": false,
  "canSendFunds": false,
  "changeType": "CREATED",
  "comment": "A very informative comment",
  "executionTimestamp": "2019-05-31 17:23:45",
  "ibans": [
    "string"
  ],
  "id": 12,
  "integratorVAT": "BE0000000196",
  "name": "Company X",
  "nationalIdentifier": "BE:VAT:BE0000000097",
  "paymentMethods": [
    "string"
  ],
  "trustedPaymentIntegratorVAT": "BE0000000295",
  "vat": "BE0000000097"
}

PaymentConfirmationNotification: object

Model representing payment request information

originBankAccount: string

The bank account of the ultimate debtor

paidAmountInCents: integer (int64)

The paid amount in cents

paymentConfirmationDate: string

The date on which the payment has been confirmed

paymentID: string

The unique identifier of the payment known by the requester

Example
{
  "originBankAccount": "BE41816373160590",
  "paidAmountInCents": 1234,
  "paymentConfirmationDate": "2019-05-31",
  "paymentID": "e529f8b4790f11e7b5a5be2e44b06b52"
}

AutoPayConfiguration: object

Model representing the settings of an auto pay configuration

changeType: string CREATE, SUSPEND, CANCEL, UPDATE, ACTIVATE

Describes the action that has to be taken on the auto pay configuration

clientID: string

Client id (known to the requestor) of the person

currency: string

The currency of the payment (ISO 4217 Currency Codes)

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

maxAmount: integer (int64)

The maximum allowed amount for the automatic payment (in cents)

paymentDate: string DUE_DATE, ONE_WEEK_BEFORE_DUE_DATE, IMMEDIATE

Defines when the payment will be executed

periodicity: string YEAR, SEMESTER, TRIMESTER, MONTH

The periodicity of the invoice

requesterID: string

The id of the requester that issued the invoice

requesterIdentificationNumber: string

The national identifier of the requester that issued the invoice

requesterVAT: string

The VAT number of the requester that issued the invoice

Example
{
  "changeType": "CREATE",
  "clientID": "Client1234",
  "currency": "EUR",
  "executionTimestamp": "2019-05-31 17:23:45",
  "maxAmount": 10000,
  "paymentDate": "ONE_WEEK_BEFORE_DUE_DATE",
  "periodicity": "MONTH",
  "requesterID": "12",
  "requesterIdentificationNumber": "BE:VAT:BE0000000097",
  "requesterVAT": "BE0000000097"
}

CustomerNotification: object

Model representing a customer notification

changeType: string OPTIN, OPTOUT

Describes the change on the customer

channel: string DIGITEAL, EMAIL, PORTAL

The channel the customer choose to receive his invoices

creditorId: integer (int64)

The Digiteal ID of the creditor

creditorName: string

The name of the creditor (first name and last name for a person)

creditorNationalIdentifier: string

The national identifier of the creditor

creditorVAT: string

The VAT number of the creditor (if any)

customerInternalId: string

Customer internal Id (as definied by the issuer)

email: string

Customer email

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

integratorVAT: string

The VAT number of the integrator

trustedPaymentIntegratorVAT: string

The VAT number of the trusted payment integrator

Example
{
  "changeType": "OPTIN",
  "channel": "DIGITEAL",
  "creditorId": 12,
  "creditorName": "Company X",
  "creditorNationalIdentifier": "BE:VAT:BE0000000097",
  "creditorVAT": "BE0000000097",
  "customerInternalId": "Customer1234",
  "email": "john.doe@me.com",
  "executionTimestamp": "2019-05-31 17:23:45",
  "integratorVAT": "BE0000000196",
  "trustedPaymentIntegratorVAT": "BE0000000295"
}

PeppolNotification: object

Model representing a PEPPOL notification

changeType: string INVOICE_RECEIVED, CREDIT_NOTE_RECEIVED, TRANSPORT_ACK_RECEIVED, INVOICE_RESPONSE_RECEIVED

PEPPOL change type

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

integratorVAT: string

The VAT number of the integrator

peppolFileContent: string

PEPPOL file content

recipientPeppolIdentifier: string

PEPPOL identifier of the recipient (type + value)

Example
{
  "changeType": "PEPPOL_INVOICE_RECEIVED",
  "executionTimestamp": "2019-05-31 17:23:45",
  "integratorVAT": "BE0000000097",
  "peppolFileContent": "Encoded in Base64",
  "recipientPeppolIdentifier": "9956:0630675588"
}

PersonNotification: object

Model representing a person notification

changeType: string CREATED, REJECTED, VALIDATED, UPDATED, PUT_ON_HOLD, CHANGED_INTEGRATOR, CHANGED_TRUSTED_PAYMENT_INTEGRATOR, DELETED

Describes the change on the person

comment: string

A comment linked to this notification.

executionTimestamp: string

The execution timestamp of the notification (format yyyy-MM-dd HH:mm:ss)

firstName: string

The first name of the person

id: integer (int64)

The Digiteal ID of the person

integratorVAT: string

The VAT number of the integrator

lastName: string

The last name of the person

trustedPaymentIntegratorVAT: string

The VAT number of the trusted payment integrator

Example
{
  "changeType": "CREATED",
  "comment": "A very informative comment",
  "executionTimestamp": "2019-05-31 17:23:45",
  "firstName": "John",
  "id": 12,
  "integratorVAT": "BE0000000097",
  "lastName": "Doe",
  "trustedPaymentIntegratorVAT": "BE0000000196"
}

PaymentRequestInformation: object

Model representing payment request information

amountInCents: integer (int64)

The amount of the invoice in cents

clientID: string

Client id (known to the requestor) of the person

creditorReference: string

The reference used by the biller to reconcile the payment. This is also called the structured communication in Belgium. It can be left empty if the remittanceInfo is defined

currency: string

The currency of the payment (ISO 4217 Currency Codes)

destinationBankAccount: string

The IBAN to which the payment has been executed

paymentID: string

The unique identifier of the payment known by the requester

paymentInternalId: string

The internal identifier of the payment as known by the creditor

paymentRequestDate: string

The date on which the invoice has been sent

paymentRequestDuedate: string

The due date of the invoice

purpose: string

The purpose based on the ISO 20022 standard

remittanceInfo: string

An unstructured string that is used as communication in the payment. This information is only used if there is nol creditorReference. It can be left empty if the creditorReference is defined

requestorID: integer (int64)

The id of the requester that issued the invoice

requestorNationalIdentifier: string

The national identifier of the requester that issued the invoice

requestorVAT: string

The VAT number of the requester that issued the invoice

Example
{
  "amountInCents": 1234,
  "clientID": "34",
  "creditorReference": "000600232562",
  "currency": "EUR",
  "destinationBankAccount": "BE41816373160590",
  "paymentID": "e529f8b4790f11e7b5a5be2e44b06b52",
  "paymentInternalId": "Payment1234",
  "paymentRequestDate": "2019-05-31",
  "paymentRequestDuedate": "2019-06-15",
  "purpose": "GDDS",
  "remittanceInfo": "Invoice1234",
  "requestorID": 12,
  "requestorNationalIdentifier": "BE:VAT:BE0000000097",
  "requestorVAT": "BE0000000097"
}
Documentation by Spectacle