> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbdpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit a User

> Add value to a user's balance.

Adds value to a user's balance, for example a reward or currency they bought through a platform store. Nothing is drawn from your funding when you credit, only when the user cashes out.

## Configuration

### Header Parameters

<ParamField required header="x-api-key" type="string">
  Your ZBD API key.
</ParamField>

<ParamField required header="Idempotency-Key" type="string">
  A UUID you generate for this credit. Retrying with the same key never credits the user twice.
</ParamField>

<ParamField initialValue="application/json" header="Content-Type" type="string">
  Content Type
</ParamField>

### Body Parameters

<ParamField required body="user_id" type="string">
  The ZBD user ID returned by Create a User.
</ParamField>

<ParamField required body="type" type="string">
  Why the user is being credited: `reward`, `purchased_token` (currency they bought through a platform store), or `adjustment`. The type decides what the user can do with the value later, including whether they can cash it out. Your ZBD contact confirms which types your program can use.
</ParamField>

<ParamField required body="amount" type="integer">
  Amount in the currency's smallest unit.
</ParamField>

<ParamField required body="currency" type="string">
  The currency code, for example `USD` or a currency you defined.
</ParamField>

<ParamField body="reference_id" type="string">
  Your own ID for this credit, returned in the transaction history.
</ParamField>

<ParamField body="description" type="string">
  Shown in the user's history.
</ParamField>

<ParamField body="project_id" type="string">
  The project the credit belongs to.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.zbdpay.com/api/v1/transactions/credits \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Idempotency-Key: 90f9371e-c48a-4bc9-9075-ef7a4c6816ec" \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
      "type": "reward",
      "amount": 1000,
      "currency": "USD",
      "reference_id": "season_3_win"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "message": "Credit completed.",
    "data": {
      "transaction_id": "txn_3b10",
      "type": "reward",
      "status": "completed",
      "user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
      "amount": 1000,
      "currency": "USD",
      "reference_id": "season_3_win"
    },
    "error": null
  }
  ```
</ResponseExample>

To take a credit back, call [Debit a User](/embedded-accounts/apis/debit) with its `transaction_id`.

## Errors

| HTTP | `code` | When |
| - | - | - |
| `400` | `idempotency_key_required` · `validation_failed` | No idempotency key, or a malformed body |
| `403` | `feature_not_enabled` | The credit `type` isn't enabled for your program |
| `404` | `user_not_found` | The user doesn't exist under your key |
| `409` | `idempotency_key_reused` | The same key was sent with a different body |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.