12. Incoming payments & rejection

Observed — bank reconciliation (validateIncomingPayment) and transaction rejection (rejectTransaction).

Why

Validate a bank-detected payment onto a rental account, or reject a transaction with a business reason.

Prerequisites

• Rental account (rentalAccountId)
• External bank IDs (externalAccountId, externalTransactionId) for automatic flows
• For rejection: rejectedReasonId (reason catalog)

12.1 Validate an incoming payment (validateIncomingPayment)

GraphQL

mutation validateIncomingPayment(
  $rentalAccountId: UUID!
  $transaction: RentalAccountAutomaticTransactionInput!
  $invoiceTransactionsToCreate: [InvoiceTransactionsToCreateInput]
) {
  validateIncomingPayment(
    rentalAccountId: $rentalAccountId
    transaction: $transaction
    invoiceTransactionsToCreate: $invoiceTransactionsToCreate
  ) {
    id
    amount
    isAutomatic
    description
    operationId
    remainingAmount
  }
}

{
  "rentalAccountId": "00000000-0000-4000-8000-000000000107",
  "transaction": {
    "amount": 25000,
    "date": "2025-09-02",
    "description": "SEPA transfer",
    "externalAccountId": 55923390,
    "externalTransactionId": 35000394070609,
    "isAutomatic": true,
    "paymentMethod": "bank_transfer",
    "sourceAccountId": "00000000-0000-4000-8000-000000000013",
    "operationId": "00000000-0000-4000-8000-000000000062"
  },
  "invoiceTransactionsToCreate": []
}

Node.js

import { ublo } from '../ubloClient.mjs';

const { validateIncomingPayment: payment } = await ublo(
  `mutation validateIncomingPayment(
    $rentalAccountId: UUID!
    $transaction: RentalAccountAutomaticTransactionInput!
    $invoiceTransactionsToCreate: [InvoiceTransactionsToCreateInput]
  ) {
    validateIncomingPayment(
      rentalAccountId: $rentalAccountId
      transaction: $transaction
      invoiceTransactionsToCreate: $invoiceTransactionsToCreate
    ) {
      id
      amount
      remainingAmount
    }
  }`,
  {
    rentalAccountId: '00000000-0000-4000-8000-000000000107',
    transaction: {
      amount: 25000,
      date: '2025-09-02',
      description: 'SEPA transfer',
      externalAccountId: 55923390,
      externalTransactionId: 35000394070609,
      isAutomatic: true,
      paymentMethod: 'bank_transfer',
      sourceAccountId: '00000000-0000-4000-8000-000000000013',
      operationId: '00000000-0000-4000-8000-000000000062',
    },
    invoiceTransactionsToCreate: [],
  },
);

console.log({ paymentId: payment.id, remaining: payment.remainingAmount });

curl

Bearer

curl -sS -X POST "$UBLO_GRAPHQL_URL" \
  -H "Authorization: Bearer $UBLO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @- <<'EOF'
{
  "query": "mutation validateIncomingPayment($rentalAccountId: UUID!, $transaction: RentalAccountAutomaticTransactionInput!, $invoiceTransactionsToCreate: [InvoiceTransactionsToCreateInput]) { validateIncomingPayment(rentalAccountId: $rentalAccountId, transaction: $transaction, invoiceTransactionsToCreate: $invoiceTransactionsToCreate) { id amount remainingAmount } }",
  "variables": {
    "rentalAccountId": "00000000-0000-4000-8000-000000000107",
    "transaction": {
      "amount": 25000,
      "date": "2025-09-02",
      "description": "SEPA transfer",
      "externalAccountId": 55923390,
      "externalTransactionId": 35000394070609,
      "isAutomatic": true,
      "paymentMethod": "bank_transfer",
      "sourceAccountId": "00000000-0000-4000-8000-000000000013",
      "operationId": "00000000-0000-4000-8000-000000000062"
    },
    "invoiceTransactionsToCreate": []
  }
}
EOF

Cookie session

curl -sS -X POST "$UBLO_GRAPHQL_URL" \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d @- <<'EOF'
{
  "query": "mutation validateIncomingPayment($rentalAccountId: UUID!, $transaction: RentalAccountAutomaticTransactionInput!, $invoiceTransactionsToCreate: [InvoiceTransactionsToCreateInput]) { validateIncomingPayment(rentalAccountId: $rentalAccountId, transaction: $transaction, invoiceTransactionsToCreate: $invoiceTransactionsToCreate) { id amount remainingAmount } }",
  "variables": {
    "rentalAccountId": "00000000-0000-4000-8000-000000000107",
    "transaction": {
      "amount": 25000,
      "date": "2025-09-02",
      "description": "SEPA transfer",
      "externalAccountId": 55923390,
      "externalTransactionId": 35000394070609,
      "isAutomatic": true,
      "paymentMethod": "bank_transfer",
      "sourceAccountId": "00000000-0000-4000-8000-000000000013",
      "operationId": "00000000-0000-4000-8000-000000000062"
    },
    "invoiceTransactionsToCreate": []
  }
}
EOF

You can also pass invoiceTransactionsToCreate to immediately attach the payment to one or more invoices (see invoice lifecycle).

12.2 Reject a transaction (rejectTransaction)

GraphQL

mutation rejectTransaction(
  $ids: [UUID!]!
  $rejectedReasonId: UUID!
  $rejectedDetails: String
  $rejectedAt: DateTime
) {
  rejectTransaction(
    ids: $ids
    rejectedReasonId: $rejectedReasonId
    rejectedDetails: $rejectedDetails
    rejectedAt: $rejectedAt
  ) {
    status
  }
}

{
  "ids": ["00000000-0000-4000-8000-000000000008"],
  "rejectedReasonId": "00000000-0000-4000-8000-000000000009",
  "rejectedDetails": null,
  "rejectedAt": "2026-08-03T00:00:00.000Z"
}

Node.js

const { rejectTransaction: result } = await ublo(
  `mutation rejectTransaction(
    $ids: [UUID!]!
    $rejectedReasonId: UUID!
    $rejectedDetails: String
    $rejectedAt: DateTime
  ) {
    rejectTransaction(
      ids: $ids
      rejectedReasonId: $rejectedReasonId
      rejectedDetails: $rejectedDetails
      rejectedAt: $rejectedAt
    ) { status }
  }`,
  {
    ids: ['00000000-0000-4000-8000-000000000008'],
    rejectedReasonId: '00000000-0000-4000-8000-000000000009',
    rejectedDetails: null,
    rejectedAt: '2026-08-03T00:00:00.000Z',
  },
);

curl

Bearer

# payload.json = query + variables from the GraphQL tab
curl -sS -X POST "$UBLO_GRAPHQL_URL" \
  -H "Authorization: Bearer $UBLO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @payload.json

Cookie session

curl -sS -X POST "$UBLO_GRAPHQL_URL" \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d @payload.json

Next

Invoice lifecycle · Read a rental folder