Pay invoices

To facilitate payments of purchase invoices, use the Document Payments APIs. Invoices can be paid individually or in bulk, using a Banqup business account or an external bank account. Regardless, the payment process follows a set of steps that ensures an easy and secure payment experience.

Prerequisites

The customer is onboarded for payments and a payment account is available.
The resource IDs necessary to perform the API calls below are:
- spaceId
- paymentId

Step 1: Validate document payments request

IMPORTANT

The first step is to validate a Document Payments request. Before a payment can be executed, the input information — such as document type, currency,and completeness — must be checked for accuracy and completeness.
The request is checked for required fields, correct data formats, and consistency with the specified document types and currencies.
If the request seems to be invalid, the errors need to be handled before trying to execute the payments request. Invalid Document Payments requests fail when using the execute payments method, so it’s crucial to ensure all input information is correct. To conclude, ensure that the Document Payments request is validated before executing it.
This API is idempotent, meaning it does not create or store any resources, ensuring consistent and repeatable results.

Endpoint: POST /solution/business/v1/spaces/{spaceId}/payment/documents:validate

Request body: View documentation

Path parameter:

spaceId

curl -L 'https://{{serverURL}}/solution/business/v1/spaces/:spaceId/payments/documents:validate' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "bulk": true,
  "documents": [
    {
      "creditorPaymentAccountId": "44285181-3714-40c0-acd2-22dd5596269e",
      "endToEndIdentification": "BTX71bdfe0f3e084871bf03d008d489c569",
      "id": "aaba0614-b8b6-05d6-94b7-957cde946300",
      "partialPaymentAmount": "150.99"
    }
  ],
  "language": "fr-FR",
  "paymentAccountId": "6da84f64-2715-4162-g3fc-2c663f46ada6",
  "redirectUrl": "https://app.btx.banqup.com/payments/payment-feedback"
}'

Successful response

{
  "valid": true,
  "validationResult": {
    "documentsErrors": [
      {
        "errors": [
          "MISSING_CREDITOR_ACCOUNT"
        ],
        "id": "aaba0614-b8b6-05d6-94b7-957cde946300"
      }
    ],
    "documentsPaymentErrors": [
      "MISSING_DEBTOR_ACCOUNT"
    ]
  }
}

Possible errors explained

Error	Description	Solution
MISSING_CREDITOR_ACCOUNT	There is no payment account associated with this supplier in the system.	Add an account on the supplier’s page to continue.
MISSING_DEBTOR_ACCOUNT	There is no payment account associated with your company in the system.	Add an account in the enterprise settings to continue.
NEGATIVE_OPEN_BALANCE	This supplier has a credit balance for this invoice.	Remove the document.
CURRENCY_MISMATCH	The currency of the invoice doesn’t match the currency of the selected debit account.	Select a different account.
INVALID_CURRENCY	The currency of this invoice is not supported.	The currency needs to be updated.
PIS_NOT_SUPPORTED	The bank associated with the selected account hasn’t been integrated in our system yet.	Select an account from a different bank.
MISSING_PAYABLE_ITEM	No invoices are selected for payment.	Add at least one invoice.

Step 2: Execute payment

Endpoint: POST /solution/business/v1/spaces/{spaceId}/payment/documents:execute

Request body: View documentation

Path parameter:

spaceId

curl -L 'https://{{serverURL}}/solution/business/v1/spaces/:spaceId/payments/documents:execute' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "bulk": true,
  "documents": [
    {
      "creditorPaymentAccountId": "44285181-3714-40c0-acd2-22dd5596269e",
      "endToEndIdentification": "BTX71bdfe0f3e084871bf03d008d489c569",
      "id": "aaba0614-b8b6-05d6-94b7-957cde946300",
      "partialPaymentAmount": "150.99"
    }
  ],
  "language": "fr-FR",
  "paymentAccountId": "6da84f64-2715-4162-g3fc-2c663f46ada6",
  "redirectUrl": "https://app.btx.banqup.com/payments/payment-feedback"
}'

Successful response

{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "redirectUrl": "http://tpp.pay-nxt.com/public/payments/callback/init?paymentPublicId=c1d00d31-ffac-4c35-afca-0e8645a93f62"
}

Step 3: View payment details and status

Once the payment has been finalized, a confirmation is received from the bank and the status of the payment is updated in Banqup.

Endpoint: GET /solution/business/v1/spaces/{spaceId}/payments/{paymentId}

Request body: View documentation

Path parameter:

spaceId
paymentId

curl -L -X GET 'https://{{serverURL}}/solution/business/v1/spaces/:spaceId/payments/:paymentId' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response

{
  "amount": {
    "currency": "EUR",
    "value": "150.99"
  },
  "documents": [
    {
      "creditor": {
        "id": "3fa85f64-5717-4562-b7fc-2c963f66afa6",
        "name": "Blue Harbour"
      },
      "documentNumber": "6793954749",
      "id": "aaba0614-b8b6-05d6-94b7-957cde946300",
      "paymentRelatedBalanceOffset": {
        "amount": {
          "currency": "EUR",
          "value": "50.05"
        },
        "id": "0639a36a-f5c2-77f8-a2db-2d60d4284362"
      }
    }
  ],
  "id": "d44698da-6363-473f-703d-8eb113a2940e",
  "status": "SUCCESSFUL"
}

Possible payment statuses

Error	Description
RECEIVED	Represents the default status right after payment initiation.
OPEN	The payment has been initiated in Banqup, but payment authorization has not yet been granted by the user in the banking/payment app.
SUCCESSFUL	The payment authorization was successfully granted. The bank starts the money flow (instant or scheduled). In this case, the open balance is updated on the document amount (see next step).
FAILED	The payment transaction was not successfully completed. Possible reasons: insufficient funds, incorrect authorization details, network issues, technical errors, currency issues, account restrictions etc.
CANCELED	Payment was canceled by the user.
UNKNOWN	The system cannot identify the payment status.

Prerequisites​

Prerequisites