# HG.Cash API

# 🚀 HG.Cash Transaction API

Modern REST API for users to create outbound transactions from their accounts.

## 🧾 How it works

- We assign accounts to your user in HG.Cash
- When these accounts have transactions (inbound or outbound), HG.Cash will notify your backend using the webhook URL you configure in the HG.Cash dashboard
- **Webhook signature (HMAC)**: In account settings you can generate a signing secret. When configured, each webhook POST includes the header `X-HG-Webhook-Signature: sha256=<hex>` where the value is HMAC-SHA256 of the raw JSON body using your secret. Verify this in your endpoint to ensure the request is authentic.
- To create cash-outs (money leaving your accounts), you must call the **Cash Out** endpoint: **Create Transaction Request (Cash Out)** (`POST /transactions`)

## 📊 Getting Started

1. **Generate your API token** in the account settings page
2. **Test endpoints** using the interactive documentation below
3. **Implement** in your backend services (never expose tokens in frontend)
4. **Monitor** your integration and handle errors appropriately

## 🔐 Authentication

This API uses **Bearer Token** authentication. Include your user API token in the Authorization header:

```
Authorization: Bearer cash_your_token_here
```

## ⚠️ Important Security Notes

- Never share or expose your user API authentication token
- Store tokens securely on your backend servers only
- All API calls must be made from secure backend services
- Contact administrators immediately if your token is compromised


Version: 1.0.0
License: MIT

## Servers

Production server
```
https://hg.cash/api/v1
```

Development server
```
http://dev.hg.cash/api/v1
```

## Security

### bearerAuth

User API authentication token with format: `cash_<64-char-hex>`

Example: `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`


Type: http
Scheme: bearer
Bearer Format: JWT

### webhookHmac

HMAC-SHA256 signature of the raw JSON body. Format: `sha256=<hex>`.
When you configure a webhook signing secret in account settings, HG.Cash includes
this header on every webhook POST. Verify the signature in your endpoint to ensure the request is authentic.


Type: apiKey
In: header
Name: X-HG-Webhook-Signature

## Download OpenAPI description

[HG.Cash API](https://docs.hg.cash/_bundle/openapi.yaml)

## Transactions

Transaction Management - Create and manage transactions in the HG.Cash system. All transaction endpoints require authentication.

### Create Transaction Request (Cash Out)

 - [POST /transactions](https://docs.hg.cash/openapi/transactions/createtransactionrequest.md): Create a new transaction request from one of your accounts. This does not perform an on-chain/bank transfer. You may provide a webhookUrl to receive status updates.

## 📝 Required Fields

- accountId: Your account ID to debit from
- toCBU or toCVU: Recipient bank CBU/CVU (22 digits)
- amount: Positive decimal number
- Optional webhookUrl: URL to receive status updates

## 🔍 Validation Rules

- Account must belong to the authenticated user
- CBU must be a valid 22-digit number
- Optional externalID must be unique per account if provided

### Get Transaction Request Status

 - [GET /transaction/{id}/status](https://docs.hg.cash/openapi/transactions/gettransactionrequeststatus.md): Retrieve the status of a transaction request created via /transactions.
Requires the bearer token of the user that created the request.

### Get Transaction Receipt

 - [GET /transactions/{id}/receipt](https://docs.hg.cash/openapi/transactions/gettransactionreceipt.md): Generate a PDF receipt for a transaction and return a signed URL to download it.
The receipt is stored in Supabase storage and cached for subsequent requests.
The signed URL expires after 1 hour.

### Get Transaction ID for Request

 - [GET /transaction-requests/{id}/transaction-id](https://docs.hg.cash/openapi/transactions/gettransactionidforrequest.md): Retrieve the linked Transaction ID for a transaction request.
Returns the actual bank transaction ID once the request has been processed (status DONE).
Returns null if the transaction has not yet been linked (e.g. still PENDING or PROCESSING).

## Accounts

Accounts - Retrieve account information and balances for the authenticated user. All account endpoints require authentication.

### Get User Accounts

 - [GET /accounts](https://docs.hg.cash/openapi/accounts/getuseraccounts.md): Returns the authenticated user's accounts.

### Get Account Balance

 - [GET /account/{id}/balance](https://docs.hg.cash/openapi/accounts/getaccountbalance.md): Returns the balance for the authenticated user's account by ID.

## Reference Data

Reference Data - Get reference data like transaction statuses and types. These endpoints require authentication.

### Look up CVU or Alias

 - [POST /alias-lookup](https://docs.hg.cash/openapi/reference-data/aliaslookup.md): Look up beneficiary information by CVU (22 digits) or alias.
Returns alias, CUIT, CVU, name, and person type.

Paid service: This endpoint is a paid feature. Usage may incur charges. Consult your accountant or HG.Cash billing team for pricing details.

### Get Transaction Statuses

 - [GET /transaction-statuses](https://docs.hg.cash/openapi/reference-data/gettransactionstatuses.md): Retrieve all available transaction statuses.

Use the returned IDs for informational purposes.

## 📋 Common Statuses

- processing: Transaction is being processed
- done: Transaction completed successfully
- failed: Transaction processing failed

### Get Transaction Types

 - [GET /transaction-types](https://docs.hg.cash/openapi/reference-data/gettransactiontypes.md): Retrieve all available transaction types.

Use the returned IDs in the typeID field when creating transactions.

## 📋 Common Types

- transfer: Bank transfer
- payment: Payment transaction
- deposit: Money deposit
- withdrawal: Money withdrawal

## Webhooks

Webhooks - Event notifications sent to your HTTP endpoint.

### Transaction Request Status Updated

 - [POST transaction-request-status-updated](https://docs.hg.cash/openapi/webhooks/transactionrequeststatusupdatedwebhook.md): HG.Cash will send this webhook when a transaction request status changes. The request body contains the request details and current status.
You can provide a webhookUrl in the create request payload, or configure a default in user settings.

### Account Movement

 - [POST account-movement](https://docs.hg.cash/openapi/webhooks/accountmovementwebhook.md): HG.Cash will send this webhook whenever money moves in or out of one of your accounts. The request body contains the movement details.

Use this to keep your internal balances and ledgers in sync with HG.Cash.

## Brazil

Transaction management - Create and manage transactions in Pix system for Brazil operations

### Create Inbound Transaction (Brazil)

 - [POST /br/transactions/inbound](https://docs.hg.cash/openapi/brazil/createbrinboundtransaction.md): Create an inbound transaction to receive a payment. Returns a QR code for the payer to scan.
Account must be a Brazil (BRL) account. Transaction starts in pending status until payment is confirmed.

### Create Outbound Transaction (Brazil)

 - [POST /br/transactions/outbound](https://docs.hg.cash/openapi/brazil/createbroutboundtransaction.md): Create an outbound transaction (withdraw) from a Brazil (BRL) account.
Requires sufficient net balance. Transaction starts in processing status.

### Get Transaction Status (Brazil)

 - [GET /br/transactions/{id}/status](https://docs.hg.cash/openapi/brazil/getbrtransactionstatus.md): Fetch the current status of a direct transaction (inbound or outbound).
Distinct from GET /transaction/{id}/status which returns TransactionRequest status.