12. Paiements entrants & rejet

Observé — rapprochement bancaire (validateIncomingPayment) et rejet de transaction (rejectTransaction).

Pourquoi

Valider un paiement détecté côté banque sur un compte locatif, ou rejeter une transaction avec un motif métier.

Prérequis

• Compte locatif (rentalAccountId)
• Identifiants externes banque (externalAccountId, externalTransactionId) si flux automatique
• Pour le rejet : rejectedReasonId (référentiel de motifs)

12.1 Valider un paiement entrant (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

Vous pouvez aussi fournir invoiceTransactionsToCreate pour rattacher immédiatement le paiement à une ou plusieurs factures (voir cycle de vie facture).

12.2 Rejeter une 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 de l’onglet GraphQL
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

Suite

Cycle de vie d’une facture · Lire un dossier