Skip to main content

Process sales invoices​


In Banqup, any uploaded file undergoes a process where invoice data is extracted and checked for sanity and accuracy. After a successful validation process, the document will be sent automatically to the customer. After that, you can view details about the document and update the payment status.

Prerequisites​

Step 1: Create file

Endpoint: /datastore/documents/transaction/v1/spaces/{spaceId}/files


Path parameter: spaceId


Requires a JSON request body (see curl example below).

curl -L -X POST 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/{spaceId}/files' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
    "filename": "S_BE0479909676_999",
    "description": "xml upload for document ABC2025-10-29",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "fileSize": 57308,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "metadata": {
        "folder": "SALES",
        "documentCategory": "INVOICE"
    }
}'

Successful response:


{
    "id": "a751dea0-cb12-4cde-8734-c6d839c863c3",
    "filename": "S_BE0479909676_999",
    "description": "xml upload for document ABC2025-10-29",
    "creatorSubject": "f3c0e3c1-a0c8-4fd4-b53a-12dbd6c28d31",
    "creatorType": "application",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "status": "AWAITING_UPLOAD",
    "fileSize": 57308,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/file/da3484f2-cd58-4039-85b1-f833d0c841da/a751dea0-cb12-4cde-8734-c6d839c863c3?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20251029%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20251029T080944Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=12564597c779d3b1a32ce1e2f6f7c322f86aafb94383fa80d65ac39b6e6b6181c14825c5bf726a17ad32f1ddb4aee65adfe149f11d620de5a4f8cedb81dbbb3a0d322aa250e926aaa0629cd5548313f08a6db5973b1b83c855c22e08641bc5b43f4ec9b5581d09be8091724f2c60eeaa6208570ecb8163c2a5cf74ccaab9f05576407bfb8689f833e0a4efa9ecf2880ff60c2bf81c7fddbffe777fd79ba47e98c506c5fc4444eab51f22142c8f468c8b5fa72c8f4bb2de384f4efb9c19bf369d3f38948555e1951c12518bac818fbd005150d711b0f42ef678ab7209575f133e4570a94782afe682967749d033a3d0dd7972f9f3ffd35b2b8b74b69e8de15be3",
    "tags": [],
    "metadata": {
        "folder": "SALES",
        "documentCategory": "INVOICE"
    },
    "createdAt": "2025-10-29T08:09:44.020545597Z",
    "updatedAt": "2025-10-29T08:09:44.020545597Z"
}

Step 2: Upload file

Endpoint: /uploadUrl (returned in the previous response).
The uploadUrl is a presigned URL in GCP which allows users to temporarily and securely access bucket resources for upload.


Request body: Attach the file in PDF, UBL or XML format. Content type: binary.


Successful response: The file has been accepted for processing. To check the file status, see step 3.1.


Invoice delivery

Document processing and delivery

If the document is processed successfully by the system, the invoice will be sent automatically to the customer.

Step 3: View results

Step 3.1: Check file status (optional)

Every newly created file undergoes a process of validation by Banqup, which is reflected in different file statuses.
Use this endpoint to check the file status.


Endpoint: /datastore/documents/transaction/v1/spaces/{spaceId}/files/{fileId}


Path parameters:

  • spaceId
  • fileId - returned in step 1.

curl -L -X 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/{spaceId}/files/{fileId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
    "id": "a751dea0-cb12-4cde-8734-c6d839c863c3",
    "filename": "S_BE0479909676_999",
    "description": "xml upload for document ABC2025-10-29",
    "creatorSubject": "f3c0e3c1-a0c8-4fd4-b53a-12dbd6c28d31",
    "creatorType": "application",
    "retentionTime": "2029-09-30T08:30:08.424Z",
    "status": "PROCESSED",
    "fileSize": 7326,
    "fileType": "application/xml",
    "contentType": "application/xml",
    "uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/transaction/file/da3484f2-cd58-4039-85b1-f833d0c841da/a751dea0-cb12-4cde-8734-c6d839c863c3?GoogleAccessId=sw-btxdata-3fac8c-uat-eu@pj-bu-btxdata-uat-eu.iam.gserviceaccount.com&Expires=1761729179&Signature=WwG1ZnR1sVhbbwnQClNs3KZA4EWSZ2vJE83XIq9t1aQHvYeLZbXh2lOPM%2Bii2xSoPSqehq2XQDYyRQqsoW6CAyQELp8ZVz%2FreOl3dl7kp857F30OA%2Fl%2FO0y3j%2FrKAXnVIasE%2FfaDna9QyXOfoyxY%2B6lHep5hWWeVvMahMbstyUP4S4tSjjRV1ll%2F9DYxxXbj1II7uwPLhPfBnQnrypdxfHGQrPJtzKGOwKcky3S1pSGZ47DHSzmW6ctBuAWryWTdoqaDjEugnODAZlxCgc9PMrNhGPyVeo0%2BUD2hJfVaiyG41vnPNmWPOlEX6oar3NmhdJsQNiPaqWaAxnFrw7zHpQ%3D%3D",
    "tags": [],
    "metadata": {
        "folder": "SALES",
        "documentCategory": "INVOICE"
    },
    "createdAt": "2025-10-29T08:09:44.020546Z",
    "updatedAt": "2025-10-29T08:12:50.610060Z"
}

Step 3.2: Retrieve the document Id

Endpoint: /datastore/documents/transaction/v1/spaces/{spaceId}/files/{fileId}/documents


Path parameters:

  • spaceId
  • fileId

curl -L -X 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/{spaceId}/files/{fileId}/documents' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
    "documents": [
        {
            "id": "53705523-fd58-4510-86f8-b7619a75a4b9"
        }
    ]
}

Step 3.3: Retrieve document info

Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}


Path parameters:

  • spaceId
  • documentId

Query parameters: optional.

  • include: processingData,validationData,connections,lines

curl -L -X 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}?include=processingData%2CvalidationData%2Cconnections%2Clines' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
    "lines": [
        {
            "id": "9e4ad3b9-a410-4a83-a531-fd4528ae0837",
            "sequence": 1,
            "data": {
                "productIdentifiers": {
                    "itemDescription": "test"
                },
                "unit": "H87",
                "quantity": "1",
                "netAmount": "20",
                "currency": "EUR",
                "id": "83l02e5b-bae7-4eef-91ec-1c7bf536f454",
                "vatDetails": {
                    "vatCategory": "S",
                    "vatPercentage": "12"
                },
                "pricing": {
                    "itemNetPrice": "20",
                    "itemPriceQuantity": "1"
                }
            }
        }
    ],
    "connections": [
        {
            "displayName": " Belgium Test Company",
            "relationType": "CUSTOMER",
            "id": "11166d33-dc4a-4af2-9588-575a26558c4f"
        }
    ],
    "id": "ff9d8da5-ae70-4ee1-a6e9-4b5085678051",
    "spaceId": "da3284f2-cd58-4039-85b1-f833d0c841da",
    "source": "documentcreator",
    "folder": "SALES",
    "status": {
        "pay": "UNPAID",
        "delivery": "RECEIVED",
        "document": "VALIDATED",
        "processing": "GENERATED_DOCUMENT_NUMBER",
        "spaceExtensions": {
            "com.unifiedpost.btx.connectors": {
                "email": {
                    "status": "DELIVERED"
                },
                "document-processor": {
                    "processing": "FINALIZED_DOCUMENT"
                }
            }
        }
    },
    "category": "INVOICE",
    "metadata": {
        "$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
        "dueDate": "2025-10-23",
        "customer": {
            "address": {
                "country": "BE",
                "postCode": " 92812",
                "townName": "ANTWERPEN",
                "streetName": "StreetName 34"
            },
            "legalName": " Belgium Test Company",
            "tradeName": " Belgium Test Company",
            "globalIdentifiers": {
                "eu:reid": "PKE_CUST-003",
                "global:email": [
                    "pjohn.smith@example.com"
                ],
                "global:participantId": "9913:PKE_CUST-003"
            }
        },
        "supplier": {
            "address": {
                "country": "BE",
                "postCode": "3110",
                "townName": "Fernandahaven",
                "streetName": "Nitzsche Lodge",
                "buildingNumber": "80728"
            },
            "legalName": "LuiTest1",
            "globalIdentifiers": {
                "flwb": "BE0417497106",
                "flwp": "PRC-d62ff2cd-7ca1-11hf-9466-8eb5ddeed38a",
                "be:en": "0417497106",
                "be:vat": "BE0417497106",
                "companyType": "BE006",
                "companyIdentifier": "BE0417497106",
                "dateOfIncorporation": "1900-01-01",
                "countryOfIncorporation": "BE",
                "primaryBusinessActivity": "474",
                "onboardingProcessInstanceId": "PRC-d69ff2cd-7ca1-11ef-9466-8eb5ddeed38a",
                "provisioningProcessInstanceId": "PRC-ekf6c3e6-7ca1-11ef-9466-8eb5ddeed38a"
            }
        },
        "issueDate": "2025-09-23",
        "vatDetails": [
            {
                "netAmount": "20",
                "vatAmount": "2.4",
                "vatCategory": "S",
                "vatPercentage": "12"
            }
        ],
        "invoiceType": "380",
        "currencyCode": "EUR",
        "documentNumber": "ABC000007",
        "documentTotals": {
            "netAmount": "20",
            "vatAmount": "2.4",
            "grossAmount": "22.4",
            "payableAmount": "22.4"
        }
    },
    "tags": [
        "SEEN"
    ],
    "retentionTime": "2036-09-23T00:00:00Z",
    "processingData": {
        "spaceExtensions": {
            "com.unifiedpost.btx.payments": {
                "aggregation": {
                    "lock": "60830b7a-cd2e-41c9-9e93-22d5eefacda1",
                    "openBalance": "22.4",
                    "projectedBalance": "22.4"
                }
            },
            "com.unifiedpost.btx.connectors": {
                "email": {
                    "reference": "da3484h2-cd58-4039-85b1-f833d0c841da/aa955a8a-d089-4096-aad4-cd4325f23819",
                    "notificationId": "8l7f946c-0774-4832-be55-3517b28de163"
                }
            }
        }
    },
    "validationData": {
        "validated": true,
        "spaceExtensions": {
            "com.unifiedpost.btx.documents.validators": {
                "general": {
                    "status": "COMPLETED",
                    "validationId": "9c742f4a-dc34-4885-bc95-298c1616629a"
                }
            },
            "com.unifiedpost.btx.connectors.validators": {
                "peppol": {
                    "status": "COMPLETED",
                    "validationId": "9c741f4a-dc34-4885-bc95-298c1616629a"
                },
                "dataExtraction": {
                    "status": "COMPLETED",
                    "validationId": "9c741f4a-dc34-4885-bc95-298c1616629a"
                }
            }
        }
    },
    "balanceOffsets": []
}

Step 4: Update payment status
info
  • Refer to this guide for a list of available payment statuses.
  • See this glossary for an explanation of possible document actions.

Step 4.1: Get available payment-related actions

To update the payment status in the next step, locate and extract the name and namespace properties corresponding to the action you want to perform, from this endpoint's response body.


Endpoint: /connectors/core/v1/spaces/{spaceId}/actions


Path parameter:

  • spaceId

Requires a JSON request body (see curl example below).

curl -L 'https://{{serverURL}}/connectors/core/v1/spaces/{spaceId}/actions' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:


{
    "actions": [
        {
            "i18n": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/i18n/label/aggr_actions_label",
            "icon": {
                "type": "BUILT_IN",
                "value": "IconPaid"
            },
            "name": "markAsPaid",
            "label": "action.markAsPaid",
            "order": 5,
            "action": {
                "dialog": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/dialog/markAsPaid",
                "basepath": "https://api.uat.btx.eu.banqup.com/pay/aggregation/documents/v2/actions/markAsPaid",
                "actionType": "callback",
                "batchDialog": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/dialog/markAsPaidBatch"
            },
            "category": "group.markAs",
            "namespace": "com.unifiedpost.btx.aggregation",
            "actionTypes": {
                "primary": "((document.folder='SALES' and document.category in ['INVOICE', 'CREDIT_NOTE']) or (document.folder='PURCHASES' and document.category in ['SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'])) and $boolean(document.status.delivery) and $not(document.status.document in ['DISPUTED', 'REFUSED', 'CANCELED']) or ((document.folder='PURCHASES' and document.category in ['INVOICE', 'CREDIT_NOTE']) or (document.folder='SALES' and document.category in ['SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'])) and $not(document.status.document in ['AWAITING_VALIDATION', 'VALIDATED', 'DISPUTED', 'REFUSED', 'CANCELED'])",
                "secondary": "true"
            },
            "permissions": {
                "allOf": [
                    {
                        "scopes": [
                            "space_write"
                        ],
                        "resourceType": "space"
                    }
                ]
            },
            "categoryIcon": {
                "type": "BUILT_IN",
                "value": "IconMarkAs"
            },
            "supportBatch": true,
            "applicability": "document.category in ['INVOICE', 'CREDIT_NOTE', 'SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'] and $number(document.processingData.spaceExtensions.'com.unifiedpost.btx.payments'.aggregation.openBalance) != 0",
            "resultNotification": "result.markAsPaid"
        },
        {
            "i18n": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/i18n/label/aggr_actions_label",
            "icon": {
                "type": "BUILT_IN",
                "value": "IconMarkAsUnpaid"
            },
            "name": "markAsUnpaid",
            "label": "action.markAsUnpaid",
            "order": 6,
            "action": {
                "dialog": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/dialog/markAsUnpaid",
                "basepath": "https://api.uat.btx.eu.banqup.com/pay/aggregation/documents/v2/actions/markAsUnpaid",
                "actionType": "callback",
                "batchDialog": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/dialog/markAsUnpaidBatch"
            },
            "category": "group.markAs",
            "namespace": "com.unifiedpost.btx.aggregation",
            "actionTypes": {
                "primary": "((document.folder='SALES' and document.category in ['INVOICE', 'CREDIT_NOTE']) or (document.folder='PURCHASES' and document.category in ['SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'])) and $boolean(document.status.delivery) and $not(document.status.document in ['DISPUTED', 'REFUSED', 'CANCELED']) or ((document.folder='PURCHASES' and document.category in ['INVOICE', 'CREDIT_NOTE']) or (document.folder='SALES' and document.category in ['SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'])) and ($not(document.status.document in ['AWAITING_VALIDATION', 'VALIDATED', 'DISPUTED', 'REFUSED', 'CANCELED']) or document.status.pay=‘FULLY_PAID’)",
                "secondary": "true"
            },
            "permissions": {
                "allOf": [
                    {
                        "scopes": [
                            "space_write"
                        ],
                        "resourceType": "space"
                    }
                ]
            },
            "categoryIcon": {
                "type": "BUILT_IN",
                "value": "IconMarkAs"
            },
            "supportBatch": true,
            "applicability": "document.category in ['INVOICE', 'CREDIT_NOTE', 'SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'] and document.processingData.spaceExtensions.'com.unifiedpost.btx.payments'.aggregation.markedAsPaid = 'true'",
            "resultNotification": "result.markAsUnpaid"
        },
        {
            "i18n": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/i18n/label/aggr_actions_label",
            "icon": {
                "type": "BUILT_IN",
                "value": "IconWontpay"
            },
            "name": "markAsWontBePaid",
            "label": "action.markAsWontBePaid",
            "order": 7,
            "action": {
                "dialog": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/dialog/markAsWontBePaid",
                "basepath": "https://api.uat.btx.eu.banqup.com/pay/aggregation/documents/v2/actions/markAsWontBePaid",
                "actionType": "callback",
                "batchDialog": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay_aggregation/action/dialog/markAsWontBePaidBatch"
            },
            "category": "group.markAs",
            "namespace": "com.unifiedpost.btx.aggregation",
            "actionTypes": {
                "primary": "((document.folder='SALES' and document.category in ['INVOICE', 'CREDIT_NOTE']) or (document.folder='PURCHASES' and document.category in ['SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'])) and $boolean(document.status.delivery) and $not(document.status.document in ['DISPUTED', 'REFUSED', 'CANCELED'])",
                "secondary": "true"
            },
            "permissions": {
                "allOf": [
                    {
                        "scopes": [
                            "space_write"
                        ],
                        "resourceType": "space"
                    }
                ]
            },
            "categoryIcon": {
                "type": "BUILT_IN",
                "value": "IconMarkAs"
            },
            "supportBatch": true,
            "applicability": "((document.folder = 'SALES' and document.category in ['INVOICE', 'CREDIT_NOTE']) or (document.folder = 'PURCHASES' and document.category in ['SELF_BILLED_INVOICE', 'SELF_BILLED_CREDIT_NOTE'])) and $number(document.processingData.spaceExtensions.'com.unifiedpost.btx.payments'.aggregation.projectedBalance) != 0",
            "resultNotification": "result.markAsWontBePaid"
        },
        {
            "i18n": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay/action/i18n/pay_tasks_label",
            "icon": {
                "type": "BUILT_IN",
                "value": "IconPaid"
            },
            "name": "pay",
            "label": "action.pay",
            "order": 10,
            "action": {
                "name": "pay",
                "actionType": "internal"
            },
            "namespace": "com.unifiedpost.btx.pay.documentActions",
            "actionTypes": {
                "primary": "(document.folder = 'PURCHASES') and (document.category in ['INVOICE', 'SELF_BILLED_INVOICE']) and (document.status.document='FULLY_APPROVED')"
            },
            "permissions": {
                "allOf": [
                    {
                        "scopes": [
                            "space_write"
                        ],
                        "resourceType": "space"
                    }
                ]
            },
            "supportBatch": true,
            "applicability": "(document.folder = 'PURCHASES') and (document.category in ['INVOICE', 'SELF_BILLED_INVOICE']) and $number(document.processingData.spaceExtensions.'com.unifiedpost.btx.payments'.aggregation.openBalance) != 0"
        },
        {
            "i18n": "https://api.uat.btx.eu.banqup.com/core/asset/v1/assets/static/pay/action/i18n/pay_tasks_label",
            "icon": {
                "type": "BUILT_IN",
                "value": "IconPaid"
            },
            "name": "pay",
            "label": "action.pay",
            "order": 10,
            "action": {
                "name": "pay",
                "actionType": "internal"
            },
            "namespace": "com.unifiedpost.btx.pay.documentActions",
            "actionTypes": {
                "primary": "document.status.document = 'ACCEPTED'"
            },
            "permissions": {
                "allOf": [
                    {
                        "scopes": [
                            "space_write"
                        ],
                        "resourceType": "space"
                    }
                ]
            },
            "supportBatch": true,
            "applicability": "(document.folder = 'PURCHASES') and (document.category in ['INVOICE', 'SELF_BILLED_INVOICE']) and (document.processingData.spaceExtensions.'com.unifiedpost.btx.payments'.aggregation.openBalance != 0) and (document.processingData.spaceExtensions.'com.unifiedpost.btx.payments'.aggregation.projectedBalance != 0)"
        }

        // [... 14 non-payment actions ("validate", "send", "delete", etc.) hidden here ...]
    ]
}

Step 4.2: Update payment status

In this example, the document will be marked as paid.


Endpoint: connectors/core/v1/spaces/actions/{namespace}/{name}/execute


Path parameters:

  • namespace: The reverse-DNS string specifying which backend module owns and processes that action. It acts as a routing scope to prevent naming collisions across different modules. E.g. com.unifiedpost.btx.aggregation
  • name: The unique identifier for a specific action or event available on a document, e.g. markAsPaid, markAsUnpaid, markAsWontBePaid.

Requires a JSON request body (see curl example below).

curl -L 'https://{{serverURL}}/connectors/core/v1/spaces/actions/{namespace}/{name}/execute' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"spaceId": "da3484u2-cd58-4039-85b1-f833d0c841da",
    "data": {
    "paymentMethod": "BANK_TRANSFER",
        "paymentReferenceNumber": "abc123",
        "paymentAmount": "60.50",
        "paymentDate": "2026-06-23T12:38:52.969Z",
        "additionalComment": "paid in full"
},
"documents": [
    "53705523-fd58-4510-86f8-b7619a75a4b9"
],
    "subject": "b7313e08-ffd7-46a1-a650-54693c180d82"
}'

Successful response:


{
    "documents": [
        {
            "documentId": "53705523-fd58-4510-86f8-b7619a75a4b9",
            "status": "SUCCESS"
        }
    ]
}
Check the response body for processing failures

The :markAsPaid endpoint returns an HTTP 200 OK status even if the documents failed to update. Your integration must inspect the response body to ensure your document IDs are not listed in the failure array.


Common reasons for failure:

  • The documentId does not exist or has been deleted.
  • The document is in an invalid state (e.g., still PROCESSING).