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.

🧾 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
  • 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
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 (Cash Out)

Request

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
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 Transaction Receipt

Request

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.

Security
bearerAuth
Path
idstring(uuid)required

Transaction ID (the actual bank transaction, not the request)

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

Responses

Signed URL to download the receipt PDF

Bodyapplication/json
signedUrlstring(uri)required

Temporary signed URL to download the receipt PDF (expires in 1 hour)

Response
application/json
{
  "signedUrl": "http://example.com"
}

Get Transaction ID for Request

Request

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

Security
bearerAuth
Path
idstring(uuid)required

Transaction request ID

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

Responses

Linked transaction ID (or null if not yet available)

Bodyapplication/json
transactionIdstring or null(uuid)required

The Transaction ID linked to this request, or null if not yet processed

Response
application/json
{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

Accounts

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

Operations

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