# Crypto Payments API

> Reconcile caller-supplied stablecoin payment records against invoices. Underpayments, overpayments, duplicate transaction hashes, and token, recipient, or chain mismatches are reported from the records in the request. No network calls are made.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/crypto-payments
- Docs: https://www.brainiac.software/api/crypto-payments/docs
- OpenAPI: https://www.brainiac.software/api/crypto-payments/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/crypto-payments/stablecoin-payment-reconcile

$0.05 USDC. 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.

Inputs: invoices, payments, rules?

Docs: https://www.brainiac.software/api/crypto-payments/docs#crypto-payments-stablecoin-payment-reconcile

Example request:

```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"
  }
}
```

Example response:

```json
{
  "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."
  ]
}
```

### POST /api/v1/crypto-payments/invoice-match-score

$0.04 USDC. 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.

Inputs: invoices, payments

Docs: https://www.brainiac.software/api/crypto-payments/docs#crypto-payments-invoice-match-score

Example request:

```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
    }
  ]
}
```

Example response:

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