Introduction

What you’ll accomplish

Claims (Reclamos) let you report Argentina bank transfer receipts when an inbound payment does not appear in your HG.cash transaction list—or when you need HG.cash to review the evidence and match it to the correct account. In the HG.cash dashboard (Claims in the sidebar), you can:

Create a claim by uploading up to 5 receipt images or PDFs per submission
Review extracted fields (COELSA code, operation number, amount, origin/destination) before submitting
Track status and comment history for each claim
Receive email when a claim is automatically matched to a transaction by COELSA code

HG.cash operations can review, change status, add internal comments, and (for scoped admins) filter claims by user or account. Beyond the dashboard, you can also create and retrieve claims programmatically through the REST API—see Create and retrieve claims via API.

Overview

Step	Who	What happens
Prepare	Merchant user or admin	Files upload to temporary storage; HG.cash extracts structured data from Argentine transfer receipts (COELSA, operation number, amount, from/to).
Confirm	Same	You confirm or edit fields, optionally link an account, and the claim is stored with evidence in the `claims` storage bucket.
Auto-match	System (production)	Every ~20 minutes, OPEN or UNDER_REVIEW claims from the last 48 hours with a valid COELSA code are matched to the latest transaction with the same code.
Manual review	HG.cash admin	Status updates and comments when auto-match does not apply or needs human judgment.

Claims focus on Argentina (ARS) transfer comprobantes. The COELSA identification code (22 alphanumeric characters when present) is the primary key for automatic reconciliation.

Claim statuses

Status	Meaning
`OPEN`	Submitted and waiting for automatic match or admin action.
`UNDER_REVIEW`	Under active review by HG.cash.
`RESOLVED`	Closed successfully—often after a transaction was found by COELSA match or manual resolution.
`REJECTED`	Not accepted (invalid evidence, duplicate, or other reason noted in comments).

Status changes and comments are timestamped in the claim history. Admins can add comments without changing status.

What gets stored on each claim

Each claim record can include:

Evidence file — image or PDF in secure storage (viewable via time-limited signed URLs in the dashboard)
COELSA code and operation number — as read from the receipt or entered by you
Amount and currency (defaults to ARS when extracted)
Extracted data — structured origin/destination hints (from, to)
Linked account — optional account you associate at creation (admins must have scope for that account)
Transaction link — set when a matching inbound transaction is found

Roles and access

Role	Typical capabilities
USER	Create claims (prepare → confirm), list own claims, view own receipt files and comments.
ADMIN	List claims for allowed accounts, filter by user/account/status, update status, add comments, export (when CAN_EXPORT is enabled).
Scoped admin	Same as admin, limited to allowed accounts (direct claim account or transaction account).

The Claims section must be enabled for your user (canAccessClaims). If you do not see Claims in the sidebar, contact HG.cash support.

Create and retrieve claims via API

You can create and read claims programmatically with the same Bearer token used for the rest of the API. The Claims feature (canAccessClaims) must be enabled for the caller. Unlike the dashboard, the API does not parse or extract data from the receipt. You must send every metadata field explicitly and attach a single file as base64.

Endpoint	Description
`POST /claims`	Create a claim with receipt evidence. Send `from`, `to`, `operationNumber`, `coelsaCode`, `amount`, `currency`, and a `file` (base64 `contentBase64`, `mimeType`, `filename`).
`GET /claims/{id}`	Retrieve a claim by ID, including a time-limited signed `fileUrl` for the stored receipt.

Key rules for the create endpoint:

Metadata is explicit — from, to, operationNumber, coelsaCode, amount, and currency are all required. There is no OCR or LLM step.
COELSA code must be exactly 22 uppercase alphanumeric characters.
File is a single attachment: base64-encoded application/pdf, image/jpeg, or image/jpg, up to 10 MB decoded, with a filename extension that matches its mimeType.
Account scope — ADMIN callers must include accountId; USER callers may omit it or associate the claim to their own account only.

curl -X POST https://hg.cash/api/v1/claims \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cash_your_token_here" \
  -d '{
    "from": "Juan Pérez",
    "to": "Mi cuenta HG",
    "operationNumber": "987654321",
    "coelsaCode": "67REZ8NPQDQ460QK94KVGO",
    "amount": 1500.00,
    "currency": "ARS",
    "file": {
      "contentBase64": "<base64-encoded PDF or image bytes>",
      "mimeType": "application/pdf",
      "filename": "comprobante.pdf"
    }
  }'

For full request and response schemas, see the Claims group in the API reference.

Webhook notifications

When a claim’s status changes—from an admin update or COELSA auto-reconcile—HG.cash POSTs a webhook to your user’s default webhook URL with topic CLAIM and eventType status_change. The body matches the GET /claims/{id} fields (without fileUrl) plus routing metadata, and an optional comment field carries the latest comment text when the update included one. Webhooks are not sent when a claim is created (the create response already contains the claim) or on comment-only updates. Configure your default webhook URL and signing secret in Settings. See Claim status updated for the full payload and Receiving webhooks for delivery, retries, and signature verification.

Automatic reconciliation

In production, a scheduled job runs approximately every 20 minutes:

Selects claims in OPEN or UNDER_REVIEW created in the last 48 hours with a non-empty COELSA code.
Finds the latest non-deleted Transaction with the same COELSA code (case-insensitive).
Sets the claim to RESOLVED, appends a system comment with the transaction ID, sends a claim matched email when your user email is on file, and emits a CLAIM / status_change webhook when your default webhook URL is configured.

If no transaction exists yet, leave the claim OPEN—matching can succeed once the inbound transfer is ingested. For older claims or missing COELSA on the receipt, rely on admin review.

When to use a claim

Use Claims when:

A payer sent an ARS bank transfer to your HG.cash account but you do not see the credit yet
You have a comprobante (screenshot or PDF) with COELSA or operation details
You need HG.cash to trace or associate the payment with a specific account

Claims are not a substitute for Checkouts hosted payment pages or the REST API for programmatic pay-ins. For Brazil PIX or Chile PayRetailers flows, use the product areas documented under Countries and Checkouts.

Before you begin

Access to Claims in the dashboard
Receipt files in image or PDF format (max 5 per submission)
COELSA code on the receipt when possible—it greatly speeds up automatic resolution
For admins: clarity on which account the transfer was intended for when linking at creation

For payment collection with hosted pages and webhooks, see Checkouts. For inbound transfer rails by country, see Countries.

Settlement

Checkouts

Claims

Developers

What you’ll accomplish

Overview

Claim statuses

What gets stored on each claim

Roles and access

Create and retrieve claims via API

Webhook notifications

Automatic reconciliation

When to use a claim

Before you begin

​What you’ll accomplish

​Overview

​Claim statuses

​What gets stored on each claim

​Roles and access

​Create and retrieve claims via API

​Webhook notifications

​Automatic reconciliation

​When to use a claim

​Before you begin

What you’ll accomplish

Overview

Claim statuses

What gets stored on each claim

Roles and access

Create and retrieve claims via API

Webhook notifications

Automatic reconciliation

When to use a claim

Before you begin