Credits | Phoenix Wallet

Credits add funds to a wallet. Each credit creates a new lot (value tranche) that can have its own attributes, expiry date, and restrictions.

Create Credit

Add funds to a wallet by creating a new lot.

POST /credits

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Yes	Unique request identifier

Request Body

Field	Type	Required	Description
`wallet_id`	string	Yes	Target wallet ID
`amount`	string	Yes	Amount to credit (decimal string)
`asset`	string	Yes	Asset type (e.g., `POINTS`, `BONUS`)
`reference`	string	No	Your reference for this transaction
`metadata`	object	No	Custom key-value pairs
`lot`	object	No	Lot configuration

Lot Configuration

Field	Type	Required	Description
`lot.expires_at`	string	No	ISO 8601 expiration timestamp
`lot.attributes`	object	No	Custom lot attributes
`lot.restrictions`	array	No	Restriction rules for this lot

Example Request

curl -X POST {{BASE_URL}}/credits \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "wallet_id": "wal_abc123def456",
    "amount": "500.00",
    "asset": "POINTS",
    "reference": "purchase_order_789",
    "metadata": {
      "source": "loyalty_program",
      "campaign": "winter_2024"
    },
    "lot": {
      "expires_at": "2024-12-31T23:59:59Z",
      "attributes": {
        "source": "promotion",
        "tier_multiplier": 1.5
      },
      "restrictions": [
        {
          "type": "category",
          "allowed": ["merchandise", "food"]
        }
      ]
    }
  }'

Example Response

{
  "data": {
    "id": "crd_xyz789abc123",
    "wallet_id": "wal_abc123def456",
    "amount": "500.00",
    "asset": "POINTS",
    "reference": "purchase_order_789",
    "status": "completed",
    "lot": {
      "id": "lot_mno456pqr789",
      "amount": "500.00",
      "asset": "POINTS",
      "expires_at": "2024-12-31T23:59:59Z",
      "attributes": {
        "source": "promotion",
        "tier_multiplier": 1.5
      },
      "restrictions": [
        {
          "type": "category",
          "allowed": ["merchandise", "food"]
        }
      ],
      "created_at": "2024-01-15T10:30:00Z"
    },
    "metadata": {
      "source": "loyalty_program",
      "campaign": "winter_2024"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	Description
`WALLET_NOT_FOUND`	Target wallet does not exist
`WALLET_SUSPENDED`	Cannot credit a suspended wallet
`INVALID_AMOUNT`	Amount must be a positive decimal
`INVALID_ASSET`	Asset type is not configured
`POLICY_VIOLATION`	Credit violates wallet policies
`VALIDATION_ERROR`	Request body validation failed

Credit with Policy Override

In some cases, you may need to credit a wallet while bypassing certain policy checks. This requires elevated permissions.

POST /credits

Additional Request Body Fields

Field	Type	Required	Description
`skip_policies`	array	No	Policy IDs to skip (requires elevated permissions)
`reason`	string	Conditional	Required when using `skip_policies`

Example Request

curl -X POST {{BASE_URL}}/credits \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "wallet_id": "wal_abc123def456",
    "amount": "1000.00",
    "asset": "POINTS",
    "reference": "manual_adjustment_001",
    "skip_policies": ["pol_max_balance"],
    "reason": "Customer service compensation - ticket #12345"
  }'

Error Codes

Code	Description
`INSUFFICIENT_PERMISSIONS`	API key does not have policy override permissions
`REASON_REQUIRED`	Reason is required when skipping policies

Bulk Credit

Credit multiple wallets in a single request.

POST /credits/bulk

Request Body

Field	Type	Required	Description
`credits`	array	Yes	Array of credit objects (max 100)
`atomic`	boolean	No	If true, all credits succeed or all fail (default: false)

Example Request

curl -X POST {{BASE_URL}}/credits/bulk \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "credits": [
      {
        "wallet_id": "wal_abc123def456",
        "amount": "100.00",
        "asset": "POINTS",
        "reference": "bulk_credit_001"
      },
      {
        "wallet_id": "wal_def456ghi789",
        "amount": "100.00",
        "asset": "POINTS",
        "reference": "bulk_credit_002"
      }
    ],
    "atomic": false
  }'

Example Response

{
  "data": {
    "successful": [
      {
        "id": "crd_xyz789abc123",
        "wallet_id": "wal_abc123def456",
        "amount": "100.00",
        "asset": "POINTS",
        "reference": "bulk_credit_001",
        "status": "completed"
      }
    ],
    "failed": [
      {
        "wallet_id": "wal_def456ghi789",
        "reference": "bulk_credit_002",
        "error": {
          "code": "WALLET_SUSPENDED",
          "message": "Cannot credit a suspended wallet"
        }
      }
    ],
    "summary": {
      "total": 2,
      "successful": 1,
      "failed": 1
    }
  }
}

Error Codes

Code	Description
`BATCH_SIZE_EXCEEDED`	More than 100 credits in batch
`ATOMIC_BATCH_FAILED`	One or more credits failed in atomic mode

Get Credit

Retrieve details of a specific credit transaction.

GET /credits/{{CREDIT_ID}}

Path Parameters

Parameter	Type	Description
`credit_id`	string	The credit ID (e.g., `crd_xyz789abc123`)

Example Request

curl -X GET {{BASE_URL}}/credits/{{CREDIT_ID}} \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

{
  "data": {
    "id": "crd_xyz789abc123",
    "wallet_id": "wal_abc123def456",
    "amount": "500.00",
    "asset": "POINTS",
    "reference": "purchase_order_789",
    "status": "completed",
    "lot": {
      "id": "lot_mno456pqr789",
      "amount": "500.00",
      "remaining": "350.00",
      "asset": "POINTS",
      "expires_at": "2024-12-31T23:59:59Z"
    },
    "metadata": {
      "source": "loyalty_program",
      "campaign": "winter_2024"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	Description
`CREDIT_NOT_FOUND`	No credit exists with this ID