Register Payments Use Case

When a debtor pays you directly (outside the platform's landing page), you should register that payment so the claim balance stays correct and collection activity stops when the debt is settled. The natural endpoint for this is credit_claims: it decreases the claim by the amount you send, keeps the payment history, and automatically resolves the claim when the balance reaches zero — no extra call needed.

Be sure to include the Authorization header with the Bearer authentication scheme and the access_token as the credentials. The access_token is provided by the authentication request.

Example:

Let's assume John Doe pays 10 euros towards his 20-euro claim. You can register the partial payment with the following request:

POST /v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/credit_claims HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "claim1": {
    "amount": 1000,
    "currency": "EUR",
    "originator": "CLIENT",
    "descriptionText": "Bank transfer ref TRX-20260710-001"
  }
}

The claim now has 10 euros outstanding and collection continues. When John later pays the remaining 10 euros (plus the 50 cents of fees), send:

POST /v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/credit_claims HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "claim1": {
    "amount": 1000,
    "fees": 50,
    "currency": "EUR",
    "originator": "CLIENT",
    "descriptionText": "Bank transfer ref TRX-20260715-002"
  }
}

The balance reaches zero, so the claim resolves automatically and all communication with the debtor stops.

Notes:

The amount and fees are the amounts being credited (in cents), not the new balance — credits are incremental, unlike update_claims, which sets absolute values.
fees can be a number (reduces the claim's total fees) or an array of { "name", "amount" } entries. When you send named fees, each credit reduces the fee bucket with the exact same name; a credit against a fee name that does not exist on the claim is silently ignored, so keep fee names consistent (see the recommended canonical names in the API reference).
The originator identifies who registered the payment. Use CLIENT for payments received on your side.
The request can include multiple claims; each one is processed and reported independently.
If a payment later bounces (direct debit reversal, chargeback), see the Payment Reversal Use Case.

FAQ

How can I get an Access Token? You can get a token using the Authentication Use Case
Should I use credit_claims or update_claims to register a payment? Prefer credit_claims. It is incremental (you send what was paid, not the resulting balance), it preserves the payment history for reporting, and it resolves the claim automatically at zero. Use update_claims when you want to set absolute values, for example when your system recomputes balances in batch.
What happens if I credit more than the outstanding balance? The claim resolves when the total reaches zero. Avoid over-crediting — reconcile the amounts on your side before sending.

FAQ

Related Pages