# HG.Cash API

# 🚀 HG.Cash Transaction API

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

## 🔐 Authentication

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

```
Authorization: Bearer cash_your_token_here
```

## 📊 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

## ⚠️ 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

## 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

 - [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. An admin will process it. 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 User Accounts

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

### Get Account Balance

 - [GET /account/{id}/balance](https://docs.hg.cash/openapi/transactions/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.

### 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.