# Tutorial: Responding to the seller via "Invoice Message Response"

Once an incoming invoice is accepted by the PSB an InvoiceReceived topic is broadcasted and will be delivered to your hooks. The PSB only accepts invoices that are technically correct. However an error could still exists on business level, for example the OrderReference is wrong or the agreed prices are incorrect. These kind of messages, together with status messages can be send back to the seller via the POST /api/v1/{partyId}/purchaseInvoice/{documentId}/response endpoint.

# Prerequisite

You have received an invoice via a hook with the topic InvoiceReceived. If not, follow the Tutorial: Receiving Invoices.
The seller supports the Invoice Message Response. This can be checked using the GET /api/v1/peppol/deliveryOption?partyIds={sellerPartyId}&documentFamily=invoiceResponse.

Or by using this form:

# Step 1: Start with an acknowledgement

The flow always start with an acknowledgement message, whatever the outcome. Acknowledgement means that you have received a readable invoice message that can be understood and submitted for processing.

Acknowledgement example:

{
  "status": "AB",
  "note": "Invoice successfully received and delivered into the administration."
}

# Step 2: Status update

Update about the process of the invoice. The next minimum status must be a "Reject" or "Approved".

Depending on the status code, a clarification reason and action may be needed.

Rejection example:

{
  "status": "RE",
  "reasons": {
    "REF": "Purchase order number is invalid. The format should be POnnnnnn."
  },
  "actions": {
    "NIN": "Please send a new invoice."
  },
  "note": "Invoice rejected due to validation errors."
}

Approval example:

{
  "status": "AP",
  "note": "Invoice accepted and will be paid on due date."
}

Paid example:

{
  "status": "PD",
  "note": "Invoice paid."
}

When additional information is needed the "Under query" status can be used.

Under query example:

{
  "status": "UQ",
   "reasons": {
    "PAY": "Payment terms not according to previous expectation."
  },
  "actions": {
    "NIN": "Please use a 2 factor for changing the IBAN."
  },
  "note": "Invoice supplier IBAN is not recognized."
}

You could also notify the seller that the invoice is in process.

In process example:

{
  "status": "IP"
}

# Step 3: Retrieve the status of the response transaction

When the response is successfully received by the receiver access point a topic InvoiceResponseSent will be broadcasted. However in case the seller doesn't support the Invoice Response Message the topic InvoiceResponseSentError will be used.

The available topics are:

InvoiceResponseSent
InvoiceResponseSentError
InvoiceResponseSentRetry

{
  "topic": "InvoiceResponseSent",
  "partyId": "NL:KVK:buyer",
  "hookId": "1",
  "documentId": "de548d14-8b84-4f7d-88fc-09b2fedf54f3",
  "message": "'InvoiceResponse' successfully sent: 'e12b19a3-30ed-4c26-b712-5112f6b24ceb@econnect.eu'.",
  "details": {
    "note": "Invoice supplier IBAN is not recognized.",
    "statusCode": "UQ",
    "status": "UnderQuery",
    "actions": {
      "nin": "Please use a 2 factor for changing the IBAN."
    },
    "reasons": {
      "pay": "Payment terms not according to previous expectation."
    }
  }
}

If you don't have a flow for the InvoiceResponseSentError, the PSB can send an email to the original sender of the document. To do this, register a mail hook that listens to the InvoiceResponseSentError like this:

{
   "id": "imr-fallback",
   "name": "mail",
   "action": "mailto:[ReceiverEmailAddress]",
   "topics": [
     "InvoiceResponseSentError"
   ],
   "isActive": true
}

← Receive invoice Receive invoice response →