Skip to content

HG.Cash API (1.0.0)

🚀 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
Download OpenAPI description
openapi.json
openapi.yaml
Overview
HG.Cash API Support
api-support@hg.cash
License
MIT
Languages
Servers
Mock server
https://docs.hg.cash/_mock/openapi/
Production server
https://hg.cash/api/v1/
Development server
http://dev.hg.cash/api/v1/

Transactions

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

Operations

Create Transaction Request

Request

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
Security
bearerAuth
Bodyapplication/jsonrequired
accountIdstring(uuid)required

ID of the user's account to send funds from

Example: "550e8400-e29b-41d4-a716-446655440123"
fromNamestring<= 255 characters

Name of the transaction sender

Example: "Juan Pérez"
toNamestring<= 255 characters

Name of the transaction recipient

Example: "María García"
fromCBUnumber

CBU (bank account number) of the sender

Example: 170001540000000020000
toCBUstring

Recipient CBU (22 digits). Provide either toCBU or toCVU.

Example: "1100015400000000000021"
toCVUstring

Recipient CVU (22 digits). Provide either toCBU or toCVU.

Example: "0000003100012345678901"
amountnumber(decimal)required

Transaction amount (must be positive)

Example: 15000.5
fromCUITnumber

CUIT/CUIL of the sender

Example: 20123456789
toCUITnumber

CUIT/CUIL of the recipient

Example: 27987654321
conceptstring<= 500 characters

Transaction concept or description

Example: "Payment for services"
externalDatestring(date-time)

Transaction date in your system (ISO 8601 format)

Example: "2024-06-19T10:30:00Z"
coelsaCodestring<= 100 characters

Coelsa transaction code

Example: "COELSA123456"
dataobject

Additional JSON data for the transaction

Example: {"reference":"REF-001","category":"services","metadata":{"source":"mobile_app","version":"1.2.3"}}
webhookUrlstring(uri)

Optional webhook URL to receive status updates for this request

Example: "https://client.example.com/webhooks/transaction-request"
curl -i -X POST \
  https://docs.hg.cash/_mock/openapi/transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "550e8400-e29b-41d4-a716-446655440123",
    "toCBU": "1100015400000000000021",
    "amount": 15000.5
  }'

Responses

Transaction request created successfully

Bodyapplication/json
idstring(uuid)

Internal transaction request ID

Example: "789e0123-e89b-12d3-a456-426614174999"
externalIDstring
Example: "REQ-2024-001234"
createdAtstring(date-time)
Example: "2024-06-19T10:30:00Z"
statusstring
Enum"PENDING""PROCESSING""DONE""ERROR"
Example: "PENDING"
Response
application/json
{
  "id": "789e0123-e89b-12d3-a456-426614174999",
  "externalID": "REQ-2024-001234",
  "createdAt": "2024-06-19T10:30:00Z",
  "status": "PENDING"
}

Get Transaction Request Status

Request

Retrieve the status of a transaction request created via /transactions. Requires the bearer token of the user that created the request.

Security
bearerAuth
Path
idstring(uuid)required

Transaction request ID

curl -i -X GET \
  'https://docs.hg.cash/_mock/openapi/transaction/{id}/status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Status retrieved

Bodyapplication/json
idstring(uuid)
externalIDstring or null
statusstring
Enum"PENDING""PROCESSING""DONE""ERROR"
errorMessagestring or null
errorCodestring or null
Enum"INSUFFICIENT_BALANCE""DESTINATION_ERROR"
createdAtstring(date-time)
updatedAtstring(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "externalID": "string",
  "status": "PENDING",
  "errorMessage": "string",
  "errorCode": "INSUFFICIENT_BALANCE",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get User Accounts

Request

Returns the authenticated user's accounts.

Security
bearerAuth
curl -i -X GET \
  https://docs.hg.cash/_mock/openapi/accounts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of accounts

Bodyapplication/json
dataArray of objects
countinteger
Response
application/json
{
  "data": [
    { … }
  ],
  "count": 0
}

Get Account Balance

Request

Returns the balance for the authenticated user's account by ID.

Security
bearerAuth
Path
idstring(uuid)required

Account ID

curl -i -X GET \
  'https://docs.hg.cash/_mock/openapi/account/{id}/balance' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Account balance

Bodyapplication/json
idstring(uuid)
balancenumber

Account balance rounded to 2 decimals

currencystring
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "balance": 0,
  "currency": "string"
}

Reference Data

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

Operations

Webhooks

Webhooks - Event notifications sent to your HTTP endpoint.

Webhooks