Stablecoin Payment Reconciliation API Documentation

POSThttps://www.brainiac.software/api/v1/crypto-payments/stablecoin-payment-reconcile$0.05 USDC

Reconcile stablecoin payment

Reconcile caller-supplied stablecoin payment records against invoices. Compares amounts, token, recipient, and chain ID, and reports underpayments, overpayments, duplicate transaction hashes, and payments that are not linked to an invoice. reconciliation_status is matched, underpaid, overpaid, duplicate, mismatched, or incomplete. Amounts are integers in smallest units. No chain is queried, and a transaction hash is not treated as confirmation that funds arrived.

Body

Field	Required	Notes
`invoices`	Yes	array; Array
`payments`	Yes	array; Array
`rules`	No	object; Object

Request exampleJSON

{
  "invoices": [
    {
      "id": "INV-100",
      "amount": "1000000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x1111111111111111111111111111111111111111"
    }
  ],
  "payments": [
    {
      "id": "p1",
      "invoiceId": "INV-100",
      "amount": "600000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x1111111111111111111111111111111111111111",
      "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "timestamp": "2026-11-05T12:00:00.000Z"
    },
    {
      "id": "p2",
      "invoiceId": "INV-100",
      "amount": "300000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x1111111111111111111111111111111111111111",
      "transactionHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    {
      "id": "p3",
      "amount": "1000000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x2222222222222222222222222222222222222222",
      "transactionHash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
    }
  ],
  "rules": {
    "allowPartial": true,
    "tolerance": "0",
    "associateUnlabeledPayments": "none"
  }
}

Response exampleJSON

{
  "reconciliation_status": "underpaid",
  "expected_amount": "1000000",
  "received_amount": "900000",
  "outstanding_amount": "100000",
  "invoices": [
    {
      "invoice_id": "INV-100",
      "reconciliation_status": "underpaid",
      "expected_amount": "1000000",
      "received_amount": "900000",
      "outstanding_amount": "100000"
    }
  ],
  "matched_payments": [
    {
      "invoice_id": "INV-100",
      "payment_id": "p1",
      "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "timestamp": "2026-11-05T12:00:00.000Z",
      "amount": "600000",
      "decimals": 6,
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "chain_id": 8453,
      "recipient": "0x1111111111111111111111111111111111111111",
      "applied_amount": "600000"
    },
    {
      "invoice_id": "INV-100",
      "payment_id": "p2",
      "transaction_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "amount": "300000",
      "decimals": 6,
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "chain_id": 8453,
      "recipient": "0x1111111111111111111111111111111111111111",
      "applied_amount": "300000"
    }
  ],
  "unmatched_payments": [
    {
      "payment_id": "p3",
      "transaction_hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "amount": "1000000",
      "decimals": 6,
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "chain_id": 8453,
      "recipient": "0x2222222222222222222222222222222222222222",
      "reason": "not_associated"
    }
  ],
  "findings": [
    {
      "code": "not_associated",
      "severity": "medium",
      "detail": "A payment has no invoice id, so it was not applied."
    },
    {
      "code": "underpaid",
      "severity": "medium",
      "invoice_id": "INV-100",
      "detail": "Invoice INV-100 received 900000 of 1000000 in its smallest units."
    }
  ],
  "limitations": [
    "Only the invoice and payment records in this request were compared. No balance or transaction was read from a chain.",
    "A transaction hash is not confirmation that funds arrived or that the transfer is final.",
    "Amounts are integers in each record's smallest unit. They are scaled by the supplied decimals with integer arithmetic.",
    "A payment is applied to an invoice only when invoiceId matches, or when associateUnlabeledPayments is single_invoice and the request contains one invoice.",
    "Partial payments are added together unless rules.allowPartial is false.",
    "Timestamps were not checked against a block time."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/crypto-payments/stablecoin-payment-reconcile" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "invoices": [
    {
      "id": "INV-100",
      "amount": "1000000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x1111111111111111111111111111111111111111"
    }
  ],
  "payments": [
    {
      "id": "p1",
      "invoiceId": "INV-100",
      "amount": "600000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x1111111111111111111111111111111111111111",
      "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "timestamp": "2026-11-05T12:00:00.000Z"
    },
    {
      "id": "p2",
      "invoiceId": "INV-100",
      "amount": "300000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x1111111111111111111111111111111111111111",
      "transactionHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    {
      "id": "p3",
      "amount": "1000000",
      "decimals": 6,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "recipient": "0x2222222222222222222222222222222222222222",
      "transactionHash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
    }
  ],
  "rules": {
    "allowPartial": true,
    "tolerance": "0",
    "associateUnlabeledPayments": "none"
  }
}
JSON

POSThttps://www.brainiac.software/api/v1/crypto-payments/invoice-match-score$0.04 USDC

Score invoice payment match

Match caller-supplied payments to invoice amounts, due dates, and fee rates in basis points. Accuracy gives 60 points to the amount, 20 to paying on time, and 20 to the fee. The discrepancy is the invoice total minus the linked payments. No chain is queried.

Body

Field	Required	Notes
`invoices`	Yes	array; Array
`payments`	Yes	array; Array

Request exampleJSON

{
  "invoices": [
    {
      "id": "INV-100",
      "amount": 1000000,
      "due_on": "2026-04-01",
      "fee_bps": 100
    }
  ],
  "payments": [
    {
      "invoice_id": "INV-100",
      "amount": 970000,
      "paid_on": "2026-04-03",
      "fee": 20000
    }
  ]
}

Response exampleJSON

{
  "reconciliation_accuracy_score": 58,
  "discrepancy_amount": 30000,
  "fee_variance_percentage": 100
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/crypto-payments/invoice-match-score" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "invoices": [
    {
      "id": "INV-100",
      "amount": 1000000,
      "due_on": "2026-04-01",
      "fee_bps": 100
    }
  ],
  "payments": [
    {
      "invoice_id": "INV-100",
      "amount": 970000,
      "paid_on": "2026-04-03",
      "fee": 20000
    }
  ]
}
JSON