Charge Management API

Create Wallet Charge

Creates a new payment charge for the wallet with QR code generation.

Endpoint

http

POST /api/wallet/{wallet}/charge/create

Parameters

wallet (integer): Wallet ID

Request Body

json

{
  "token": "ETH",
  "amount": 0.1,
  "expires": 300,
  "mode": "dynamic"
}

Request Parameters

token (string, required): Token symbol
amount (numeric, required): Charge amount
expires (numeric, optional): Expiration time in seconds (default: 300)
mode (string, optional): Charge mode - "dynamic" or "static" (default: "dynamic")

Response

json

{
  "status": "success",
  "message": "Wallet charge made successfully",
  "data": {
    "id": 1,
    "wallet_id": 1,
    "sub_wallet_id": null,
    "token_id": 1,
    "amount": "0.100000000000000000",
    "status": "pending",
    "mode": "dynamic",
    "expires": 300,
    "content": "ethereum:0x0b88b41fdc5b2127c4082145fc34828b7d20a301@97?data=0xa9059cbb0000000000000000000000000b88b41fdc5b2127c4082145fc34828b7d20a3010000000000000000000000000000000000000000000000000058d15e17628000",
    "info": null,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-01 00:00:00"
  }
}

Example Request

bash

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"token":"ETH","amount":0.1,"expires":300,"mode":"dynamic"}' \
     https://zafira-app.vratts.com/api/wallet/1/charge/create

Get Wallet Charge

Retrieves details for a specific charge.

Endpoint

http

GET /api/wallet/{wallet}/charge/show/{charge}

Parameters

wallet (integer): Wallet ID
charge (integer): Charge ID

Response

json

{
  "status": "success",
  "message": "Charge fetched successfully",
  "data": {
    "id": 1,
    "wallet_id": 1,
    "sub_wallet_id": null,
    "token_id": 1,
    "amount": "0.100000000000000000",
    "status": "pending",
    "mode": "dynamic",
    "expires": 300,
    "content": "ethereum:0x0b88b41fdc5b2127c4082145fc34828b7d20a301@97?data=0xa9059cbb0000000000000000000000000b88b41fdc5b2127c4082145fc34828b7d20a3010000000000000000000000000000000000000000000000000058d15e17628000",
    "info": null,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-01 00:00:00"
  }
}

Example Request

bash

curl -H "Authorization: Bearer {token}" \
     https://zafira-app.vratts.com/api/wallet/1/charge/show/1

Charge Model Details

Fields

id (integer): Unique charge identifier
wallet_id (integer): Associated wallet ID
sub_wallet_id (integer, nullable): Associated sub-wallet ID
token_id (integer): Associated token ID
amount (decimal): Charge amount (18 decimal places)
status (string): Charge status (auto-calculated)
mode (string): Charge mode ("dynamic" or "static")
expires (integer): Expiration time in seconds from creation
content (text): QR code content for payment
info (text, nullable): Additional charge information
uuid (string): Unique identifier for payment link
created_at (datetime): Creation timestamp
updated_at (datetime): Last update timestamp

Charge Status Logic

The status is automatically calculated based on expiration time:

pending: Charge created but not yet paid
confirmed: Charge has been paid
failed: Payment failed
expired: Charge expired without payment

Charge Modes

dynamic: Amount can be adjusted by payer
static: Fixed amount, cannot be changed

Payment Link Generation

QR Code Content

The content field contains the QR code data in URI format:

ethereum:0x0b88b41fdc5b2127c4082145fc34828b7d20a301@97?data=0xa9059cbb...

Payment Link URL

Use the UUID to generate payment links:

https://zafira-app.domain.com/wallet/pay/{uuid}

For example, with UUID edc86a93-f0ef-4bd7-a203-b48ee02f5c06:

https://zafira-app.domain.com/wallet/pay/edc86a93-f0ef-4bd7-a203-b48ee02f5c06

QR Code Integration

The content field can be used directly with QR code generation libraries:

javascript

// Example QR code generation
const QRCode = require('qrcode');
const qrContent = charge.data.content;
const qrCodeImage = await QRCode.toDataURL(qrContent);

Charge Expiration

Expiration Handling

Charges automatically expire after the specified time
Expiration time is calculated from creation timestamp
Expired charges cannot be paid
Status automatically updates to "expired"

Default Expiration

Default expiration: 300 seconds (5 minutes)
Maximum expiration: 3600 seconds (1 hour)
Minimum expiration: 60 seconds (1 minute)

Error Handling

Common Errors

Charge Not Found (404)

json

{
  "status": "error",
  "message": "Charge not found",
  "data": null
}

Invalid Amount (422)

json

{
  "status": "error",
  "message": "The amount field is required",
  "data": {
    "amount": ["The amount field is required."]
  }
}

Invalid Token (422)

json

{
  "status": "error",
  "message": "The token field is required",
  "data": {
    "token": ["The token field is required."]
  }
}

Invalid Expiration (422)

json

{
  "status": "error",
  "message": "The expires field must be between 60 and 3600",
  "data": {
    "expires": ["The expires field must be between 60 and 3600."]
  }
}

Charge Expired (400)

json

{
  "status": "error",
  "message": "Charge has expired",
  "data": null
}

Charge Lifecycle

1. Creation

Charge is created with specified amount and expiration
UUID is generated for payment link
QR code content is generated
Status is set to "pending"

2. Payment Processing

Payment is detected on blockchain
Status updates to "confirmed"
Webhook notifications are triggered
Balance is updated

3. Expiration

If not paid within expiration time
Status automatically updates to "expired"
Charge becomes unusable

4. Completion

Charge remains in database for record keeping
Can be retrieved for historical purposes
Status reflects final state

Webhook Integration

Charge Events

Charges trigger webhook events:

charge.created: When charge is created
charge.paid: When payment is confirmed
charge.expired: When charge expires
charge.failed: When payment fails

Webhook Payload Example

json

{
  "event": "charge.paid",
  "data": {
    "charge_id": 1,
    "wallet_id": 1,
    "amount": "0.100000000000000000",
    "token": "ETH",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "confirmed"
  }
}

Best Practices