# Balance & Transactions

### Customer Balance

Retrieve the real-time balance of a customer's E-Wallet.

### `GET /customers/{customerId}/balance` - Get Balance

Returns the current balance in cents.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| customerId | integer | Yes | Customer ID |
| unscoped | boolean | No | Bypass scope checks if needed. |

#### Response

```json
{
  "status": 200,
  "code": "balance_succeed",
  "message": "Vous avez accès à ce contenu.",
  "data": {
    "customerBalance": -147000
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "balance\_succeed" | Machine-readable application code for the result. |
| message | string | "Vous avez accès à ce contenu." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.customerBalance | integer | \-147000 | The customer balance value. |

### Customer History

Retrieve a chronological list of all movements on the customer's wallet, including orders, reloads, and manual adjustments.

### `GET /customers/{customerId}/balance_history` - Get Balance History

Retrieve a list of wallet transactions (credits, debits, orders).

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| customerId | integer | Yes | Customer ID |
| include | string | No | Relations to include (e.g., "beforeAndAfterBalance,omnichannelOrder"). |
| limit | integer | No | Pagination limit (default 10). |
| offset | integer | No | Pagination offset (default 0). |
| order | string | No | Sort order (e.g. "-createdAt"). |
| unscoped | boolean | No | Bypass scope checks. |

#### Response

```json
{
  "status": 200,
  "code": "balance_succeed",
  "message": "You have access to this balance.",
  "data": [
    {
      "transactionId": 483134,
      "type": "1",
      "currency": "EUR",
      "amount": 50000,
      "paymentOrigin": "1",
      "customerId": 510,
      "createdAt": "2023-08-30T10:02:15.000Z",
      "source": "1",
      "balanceBefore": -197000,
      "balanceAfter": -147000
    },
    {
      "transactionId": 410706,
      "type": "3",
      "currency": "EUR",
      "amount": -300000,
      "customerId": 510,
      "createdAt": "2023-05-05T14:41:36.000Z",
      "source": "2",
      "balanceBefore": 103000,
      "balanceAfter": -197000,
      "omnichannelOrder": {
        "reportOrderId": 239190,
        "omnichannelOrderId": "286911",
        "totalPriceDiscountedWithTaxIncluded": 300000,
        "items": [
          {
            "name": "Eau Nestlé",
            "quantity": 1000,
            "totalPriceWithTaxIncluded": 300000
          }
        ]
      }
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "balance\_succeed" | Machine-readable application code for the result. |
| message | string | "You have access to this balance." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].transactionId | integer | 483134 | Identifier of the transaction. |
| data\[\].type | string | "1" | The type value. |
| data\[\].currency | string | "EUR" | ISO 4217 currency code. |
| data\[\].amount | integer | 50000 | The amount value. |
| data\[\].paymentOrigin | string | "1" | The payment origin value. |
| data\[\].customerId | integer | 510 | Identifier of the customer. |
| data\[\].createdAt | string | "2023-08-30T10:02:15.000Z" | Timestamp when this resource was created. |
| data\[\].source | string | "1" | The source value. |
| data\[\].balanceBefore | integer | \-197000 | The balance before value. |
| data\[\].balanceAfter | integer | \-147000 | The balance after value. |

### Get Transactions

Retrieve a general list of E-Wallet transactions. This endpoint allows for filtering by date range, brand, or pagination.

### `GET /transactions` - Get Transactions

Retrieve transactions executed within the system. Supports optional filtering.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | No | Filter by Brand ID. |
| startDate | string | No | Filter start date (ISO 8601). |
| endDate | string | No | Filter end date (ISO 8601). |
| offset | integer | No | Pagination offset. |
| limit | integer | No | Pagination limit. |

#### Response

```json
{
  "status": 200,
  "code": "transactions_succeed",
  "message": "Les transactions se sont executées avec succès.",
  "data": [
    {
      "customerId": 431986,
      "firstName": "Alice",
      "lastName": "Doe",
      "email": "alice.doe@example.com",
      "class": "CLASS_A",
      "section": "SECTION_1",
      "subSection": "SUB_1",
      "accountPaymentType": "POSTPAYMENT",
      "studentNumber": null,
      "pricingRuleCode": "SUBV_TYPE_A",
      "badgeNumber": null,
      "sourceUserId": 69671,
      "sourceUserFirstName": "Admin",
      "sourceUserLastName": "User",
      "sourceUserEmail": "admin@example.com",
      "applyDate": "2020-07-02T09:43:07.000Z",
      "creationDate": "2020-07-02T09:43:07.000Z",
      "transactionId": 4289237,
      "brandId": 491,
      "restaurantId": null,
      "restaurantName": null,
      "orderId": null,
      "externalOrderReference": null,
      "transactionAmount": 1280,
      "transactionType": "1",
      "paymentOrigin": "3",
      "paymentOriginMetadata": "Manual adjustment",
      "transactionStatus": "1",
      "transactionSource": "1",
      "externalUserReference": null,
      "currency": "EUR"
    },
    {
      "customerId": 321400,
      "firstName": "Bob",
      "lastName": "Smith",
      "email": "bob.smith@example.com",
      "transactionId": 4405098,
      "transactionAmount": 474,
      "transactionType": "1",
      "paymentOrigin": "3",
      "paymentOriginMetadata": "Subsidy adjustment",
      "transactionStatus": "1",
      "transactionSource": "1",
      "currency": "EUR"
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "transactions\_succeed" | Machine-readable application code for the result. |
| message | string | "Les transactions se sont executées avec succès." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].customerId | integer | 431986 | Identifier of the customer. |
| data\[\].firstName | string | "Alice" | The first name value. |
| data\[\].lastName | string | "Doe" | The last name value. |
| data\[\].email | string | "alice.doe@example.com" | Email address. |
| data\[\].class | string | "CLASS\_A" | The class value. |
| data\[\].section | string | "SECTION\_1" | The section value. |
| data\[\].subSection | string | "SUB\_1" | The sub section value. |
| data\[\].accountPaymentType | string | "POSTPAYMENT" | The account payment type value. |
| data\[\].studentNumber | null | null | The student number value. |
| data\[\].pricingRuleCode | string | "SUBV\_TYPE\_A" | The pricing rule code value. |
| data\[\].badgeNumber | null | null | The badge number value. |
| data\[\].sourceUserId | integer | 69671 | Identifier of the associated source user. |
| data\[\].sourceUserFirstName | string | "Admin" | The source user first name value. |
| data\[\].sourceUserLastName | string | "User" | The source user last name value. |
| data\[\].sourceUserEmail | string | "admin@example.com" | The source user email value. |
| data\[\].applyDate | string | "2020-07-02T09:43:07.000Z" | Date or timestamp for apply. |
| data\[\].creationDate | string | "2020-07-02T09:43:07.000Z" | Date or timestamp for creation. |
| data\[\].transactionId | integer | 4289237 | Identifier of the transaction. |
| data\[\].brandId | integer | 491 | Identifier of the brand. |
| data\[\].restaurantId | null | null | Identifier of the restaurant. |
| data\[\].restaurantName | null | null | The restaurant name value. |
| data\[\].orderId | null | null | Identifier of the order. |
| data\[\].externalOrderReference | null | null | The external order reference value. |
| data\[\].transactionAmount | integer | 1280 | The transaction amount value. |
| data\[\].transactionType | string | "1" | The transaction type value. |
| data\[\].paymentOrigin | string | "3" | The payment origin value. |
| data\[\].paymentOriginMetadata | string | "Manual adjustment" | The payment origin metadata value. |
| data\[\].transactionStatus | string | "1" | The transaction status value. |
| data\[\].transactionSource | string | "1" | The transaction source value. |
| data\[\].externalUserReference | null | null | The external user reference value. |
| data\[\].currency | string | "EUR" | ISO 4217 currency code. |

### Create E-Wallet Transaction

Create an E-Wallet transaction (credit, debit, refund, etc.) for a customer identified by ID, student number, or badge number. This endpoint supports external order references and partial payment acceptance.

### `POST /transactions/ewallet` - Create E-Wallet Transaction

Create a new E-Wallet transaction. The customer can be identified by customerId, studentNumber, or badgeNumber (at least one is required). Either paymentOrigin or externalOrderReference must be provided.

#### Request Body

```json
{
  "brandId": 491,
  "customerId": 130069,
  "amount": 500,
  "type": "1",
  "source": "7",
  "paymentOrigin": "4",
  "restaurantId": 1234,
  "paymentOriginMetaData": "Online reload via API",
  "externalOrderReference": "EXT-ORD-001",
  "externalUserReference": "EXT-USR-001",
  "externalUserReferenceId": "abc-123",
  "externalDailyOrderId": "DAILY-001",
  "deviceId": "device-001",
  "uniqueTransactionId": "unique-txn-001",
  "acceptPartialTransaction": false,
  "isPartialPaymentAccepted": false,
  "unitCurrency": false
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| brandId | integer | Yes | 491 | Brand ID the transaction belongs to. |
| customerId | integer | No | 130069 | Customer ID. At least one of customerId, studentNumber, or badgeNumber is required. |
| amount | integer | Yes | 500 | Transaction amount in cents. |
| type | string | Yes | "1" | Transaction type: "1" (CREDIT), "2" (REFUND), "3" (DEBIT), "4" (CANCEL), "5" (DATE\_MODIFICATION), "6" (POST\_PAYMENT\_RESET). |
| source | string | Yes | "7" | Transaction source: "7" for API integration. |
| paymentOrigin | string | No | "4" | Payment origin code (see Types). Required if externalOrderReference is not provided. |
| restaurantId | integer | No | 1234 | Restaurant ID associated with the transaction. |
| paymentOriginMetaData | string | No | "Online reload via API" | Additional metadata about the payment origin. |
| externalOrderReference | string | No | "EXT-ORD-001" | External order reference. Required if paymentOrigin is not provided. |
| externalUserReference | string | No | "EXT-USR-001" | External user reference for tracking. |
| externalUserReferenceId | string | No | "abc-123" | External user reference ID. |
| externalDailyOrderId | string | No | "DAILY-001" | External daily order identifier. |
| deviceId | string | No | "device-001" | Device identifier that initiated the transaction. |
| uniqueTransactionId | string | No | "unique-txn-001" | Idempotency key to prevent duplicate transactions. |
| acceptPartialTransaction | boolean | No | false | Accept partial transaction if balance is insufficient. |
| isPartialPaymentAccepted | boolean | No | false | Whether partial payment is accepted. |
| unitCurrency | boolean | No | false | If true, amount is in unit currency rather than cents. |
| studentNumber | string | No | Not provided | Student number to identify the customer. |
| badgeNumber | string | No | Not provided | Badge number to identify the customer. |

#### Response

```json
{
  "status": 200,
  "code": "transaction_succeed",
  "message": "Transaction has been proceed with success.",
  "data": {
    "transactionId": 592901,
    "amount": 500,
    "type": "1",
    "source": "7",
    "paymentOrigin": "4",
    "brandId": 491,
    "customerId": 130069,
    "restaurantId": 1234,
    "currency": "EUR",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "customer": {
      "customerId": 130069,
      "firstName": "Alice",
      "lastName": "Doe",
      "email": "alice.doe@example.com",
      "studentNumber": null,
      "classroom": null,
      "oldBalance": "1000",
      "newBalance": "1500"
    }
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "transaction\_succeed" | Machine-readable application code for the result. |
| message | string | "Transaction has been proceed with success." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.transactionId | integer | 592901 | Identifier of the transaction. |
| data.amount | integer | 500 | The amount value. |
| data.type | string | "1" | The type value. |
| data.source | string | "7" | The source value. |
| data.paymentOrigin | string | "4" | The payment origin value. |
| data.brandId | integer | 491 | Identifier of the brand. |
| data.customerId | integer | 130069 | Identifier of the customer. |
| data.restaurantId | integer | 1234 | Identifier of the restaurant. |
| data.currency | string | "EUR" | ISO 4217 currency code. |
| data.createdAt | string | "2024-01-15T10:30:00.000Z" | Timestamp when this resource was created. |
| data.customer | object | {…} | Object containing customer fields. |
| data.customer.customerId | integer | 130069 | Identifier of the customer. |
| data.customer.firstName | string | "Alice" | The first name value. |
| data.customer.lastName | string | "Doe" | The last name value. |
| data.customer.email | string | "alice.doe@example.com" | Email address. |
| data.customer.studentNumber | null | null | The student number value. |
| data.customer.classroom | null | null | The classroom value. |
| data.customer.oldBalance | string | "1000" | The old balance value. |
| data.customer.newBalance | string | "1500" | The new balance value. |

### `DELETE /transactions/{transactionId}` - Cancel E-Wallet Transaction

Creates an opposite CANCEL transaction for the referenced transaction. A transaction can only be cancelled once; the caller must be allowed to read the transaction customer.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| transactionId | integer | Yes | Existing transaction to cancel. |
| source | string | Yes | Source code recorded on the cancellation transaction: 1 Dashboard, 2 CEL, 3 E-Wallet Reloader, 4 Reception, 5 POS, 6 Kiosk, 7 API, 8 E-Wallet Kiosk, 9 Vending machine, or 10 System. |

#### Request Body

```json
{
  "externalUserReference": "refund-operator-42"
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| externalUserReference | string | No | "refund-operator-42" | Optional external operator or user reference stored on the cancellation transaction. |

#### Response

```json
{
  "status": 200,
  "code": "transaction_succeed",
  "message": "Transaction has been proceed with success.",
  "data": {
    "transactionId": 592902,
    "uniqueTransactionId": "bd4c80cd-6e25-4d07-9ac1-688cbd4b26f5",
    "amount": -500,
    "error": null,
    "type": "4",
    "status": "1",
    "remoteAddress": "203.0.113.10",
    "source": "7",
    "currency": "EUR",
    "externalUserReference": "refund-operator-42",
    "externalUserReferenceId": null,
    "externalOrderReference": "EXT-ORD-001",
    "externalDailyOrderId": "DAILY-001",
    "externalDeviceId": null,
    "sourceUserId": 130069,
    "originTransactionId": 592901,
    "paymentOrigin": null,
    "paymentOriginMetaData": null,
    "brandId": 491,
    "restaurantId": 1234,
    "customerId": 130069,
    "userId": null,
    "orderId": null,
    "groupTransactionId": null,
    "loyaltyCardId": null,
    "applyDate": "2026-07-11T09:30:00.000Z",
    "created_at": "2026-07-11T09:30:00.000Z",
    "updated_at": "2026-07-11T09:30:00.000Z",
    "deleted_at": null
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "transaction\_succeed" | Machine-readable application code for the result. |
| message | string | "Transaction has been proceed with success." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.transactionId | integer | 592902 | Identifier of the transaction. |
| data.uniqueTransactionId | string | "bd4c80cd-6e25-4d07-9ac1-688cbd4b26f5" | Identifier of the associated unique transaction. |
| data.amount | integer | \-500 | The amount value. |
| data.error | null | null | The error value. |
| data.type | string | "4" | The type value. |
| data.status | string | "1" | HTTP status code returned by the API. |
| data.remoteAddress | string | "203.0.113.10" | The remote address value. |
| data.source | string | "7" | The source value. |
| data.currency | string | "EUR" | ISO 4217 currency code. |
| data.externalUserReference | string | "refund-operator-42" | The external user reference value. |
| data.externalUserReferenceId | null | null | Identifier of the associated external user reference. |
| data.externalOrderReference | string | "EXT-ORD-001" | The external order reference value. |
| data.externalDailyOrderId | string | "DAILY-001" | Identifier of the associated external daily order. |
| data.externalDeviceId | null | null | Identifier of the associated external device. |
| data.sourceUserId | integer | 130069 | Identifier of the associated source user. |
| data.originTransactionId | integer | 592901 | Identifier of the associated origin transaction. |
| data.paymentOrigin | null | null | The payment origin value. |
| data.paymentOriginMetaData | null | null | The payment origin meta data value. |
| data.brandId | integer | 491 | Identifier of the brand. |
| data.restaurantId | integer | 1234 | Identifier of the restaurant. |
| data.customerId | integer | 130069 | Identifier of the customer. |
| data.userId | null | null | Identifier of the user. |
| data.orderId | null | null | Identifier of the order. |
| data.groupTransactionId | null | null | Identifier of the associated group transaction. |
| data.loyaltyCardId | null | null | Identifier of the associated loyalty card. |
| data.applyDate | string | "2026-07-11T09:30:00.000Z" | Date or timestamp for apply. |
| data.created\_at | string | "2026-07-11T09:30:00.000Z" | Timestamp when this resource was created. |
| data.updated\_at | string | "2026-07-11T09:30:00.000Z" | Timestamp when this resource was last updated. |
| data.deleted\_at | null | null | Timestamp when this resource was deleted, or null when it is active. |

### Transfer Full E-Wallet Balance

Move the complete positive balance from one customer to another customer in the same brand. The API creates one debit and one credit atomically; it does not accept a partial amount.

### `POST /transactions/ewallet/transfer` - Transfer Full Customer Balance

Transfers 100% of the source customer balance. The source and destination must be different customers in the same e-wallet-enabled brand. Transfers from post-payment accounts and zero or negative balances are rejected.

#### Request Body

```json
{
  "brandId": 491,
  "sourceCustomerId": 130069,
  "destinationCustomerId": 130070
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| brandId | integer | Yes | 491 | Brand shared by both customers. |
| sourceCustomerId | integer | Yes | 130069 | Customer whose entire current balance will be debited. |
| destinationCustomerId | integer | Yes | 130070 | Customer who receives the transferred balance. |

#### Response

```json
{
  "status": 201,
  "code": "transfer_ewallet_succeed",
  "message": "Balance transfer has been completed with success.",
  "data": {
    "amount": 1500,
    "currency": "EUR",
    "groupTransactionId": "0dbd40ce-7eb1-49ae-b446-5b4e6c5e6f99",
    "source": {
      "customerId": 130069,
      "firstName": "Alice",
      "lastName": "Doe",
      "transactionId": 592902,
      "oldBalance": 1500,
      "newBalance": 0
    },
    "destination": {
      "customerId": 130070,
      "firstName": "Bob",
      "lastName": "Smith",
      "transactionId": 592903,
      "oldBalance": 500,
      "newBalance": 2000
    }
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 201 | HTTP status code returned by the API. |
| code | string | "transfer\_ewallet\_succeed" | Machine-readable application code for the result. |
| message | string | "Balance transfer has been completed with success." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.amount | integer | 1500 | The amount value. |
| data.currency | string | "EUR" | ISO 4217 currency code. |
| data.groupTransactionId | string | "0dbd40ce-7eb1-49ae-b446-5b4e6c5e6f99" | Identifier of the associated group transaction. |
| data.source | object | {…} | Object containing source fields. |
| data.source.customerId | integer | 130069 | Identifier of the customer. |
| data.source.firstName | string | "Alice" | The first name value. |
| data.source.lastName | string | "Doe" | The last name value. |
| data.source.transactionId | integer | 592902 | Identifier of the transaction. |
| data.source.oldBalance | integer | 1500 | The old balance value. |
| data.source.newBalance | integer | 0 | The new balance value. |
| data.destination | object | {…} | Object containing destination fields. |
| data.destination.customerId | integer | 130070 | Identifier of the customer. |
| data.destination.firstName | string | "Bob" | The first name value. |
| data.destination.lastName | string | "Smith" | The last name value. |
| data.destination.transactionId | integer | 592903 | Identifier of the transaction. |
| data.destination.oldBalance | integer | 500 | The old balance value. |
| data.destination.newBalance | integer | 2000 | The new balance value. |