> ## Documentation Index > Fetch the complete documentation index at: https://docs.omneo.io/llms.txt > Use this file to discover all available pages before exploring further. # Balance sync > How Givex BALANCE events update Omneo Credits, when a new Credit is created, and the responses Givex receives. Givex sends a `BALANCE` event whenever a card's balance changes. The extension applies each event to the Omneo **Credit** that represents the card, so the balance shown on a Profile in Omneo matches Givex. ## What Givex sends | Field | Required | Used for | | ----------------------- | -------- | ---------------------------------------------------------------------------------------------- | | `uuid` | Yes | Identifies the event. Repeated deliveries of the same `uuid` are ignored. | | `eventDate` | Yes | Orders events. An event older than the last applied one is ignored. | | `cardNumber` | Yes | The masked card number, used to find the Credit. | | `balance` | Yes | The new remaining balance, as a plain decimal such as `150.00`. | | `currency` | No | Checked against the Credit Definition currency when both are known. | | `expiryDate` | No | Sets the Credit expiry to the end of that day. | | `cardFaceNumber` | No | The full printed card number, stored as the Credit's `credit_number` when a Credit is created. | | `cardFaceName` | No | Matched against Credit Definition names to choose the definition when a Credit is created. | | `email` | No | Matched against Omneo Profiles to assign the Credit. | | `firstName`, `lastName` | No | Used for the Profile name when `create_profile_if_missing` creates one. | | `pin` | No | Stored as the Credit's `security_code` when a Credit is created. | | `activationDate` | No | Becomes `issued_at` when a Credit is created. | | `activationAmount` | No | Becomes `value_initial` when a Credit is created. | Event types other than `BALANCE` are accepted and ignored. Givex has not confirmed the final names for the email, card face name and Profile name fields, so these four are read through the `event_field_mapping` setting and can be pointed at whatever names your Givex account sends. The names above are the defaults. See [Setup](/extensions/givex/setup). ## How the Credit is found Omneo looks for exactly one Credit whose `external_id` equals the masked card number in the `givex` namespace. If none is found, it looks for a Credit whose `credit_number` equals the masked card number. If more than one Credit matches, nothing is changed and the event is rejected so the duplicate can be resolved. ## What is updated When a Credit matches, Omneo sets: | Credit field | Value | | ----------------- | ------------------------------------------------------------------------------------------------------- | | `value_remaining` | The event `balance` | | `expires_at` | The end of the event `expiryDate`, in the Credit's timezone. Left unchanged if the event has no expiry. | | `meta.givex` | The last applied event's `uuid`, date, balance and currency, and the time of the sync | Events are ignored without changes when the `uuid` has already been applied or when the `eventDate` is older than the last applied event. An event whose currency does not match the Credit Definition currency is rejected and nothing is written. If the matched Credit has no Profile and the event carries an email address that matches an Omneo Profile, the Credit is assigned to that Profile in the same update. ## When a Credit is created If no Credit matches, Omneo picks a Credit Definition in this order: 1. The Credit Definition whose name is exactly the `cardFaceName` on the event. 2. The Credit Definition named by the `credit_definition_handle` setting. If neither is available, no Credit is created. Omneo then creates the Credit under the chosen definition: * `value_remaining` is the event balance and `value_initial` is the activation amount, or the balance if Givex did not send one. * `external_id` is the masked card number in the `givex` namespace, and `credit_number` is the full card number when Givex sends it. * `is_imported` is `true`, so reporting can separate Givex-originated Credits from Credits issued in Omneo. The Credit is assigned to a Profile when the event's email address matches one. When it matches none, `create_profile_if_missing` decides: `true` creates the Profile from the event's name fields and assigns the Credit to it, `false` leaves the Credit unassigned for you to assign in Omneo later. If no Credit Definition can be chosen, the card is not created and the event is answered with `404`. Givex retries these, so if you do not intend unknown cards to become Credits, ask Givex to stop sending events for cards outside your Omneo program rather than leaving them to retry. ## Responses Givex receives | Response | Meaning | Givex action | | -------- | -------------------------------------------------------------------------- | -------------------------------------- | | `200` | Applied, already applied, or ignored as older | None | | `201` | A new Credit was created | None | | `400` | The event body is malformed | Fix and resend | | `401` | The event is not signed with the agreed secret | Check the secret with Omneo | | `404` | No Credit matches and no Credit Definition could be chosen | Retry later | | `409` | More than one Credit matches the card | Contact Omneo to resolve the duplicate | | `422` | Required fields missing, balance not a plain decimal, or currency mismatch | Fix and resend | | `5xx` | Omneo could not apply the event | Retry later | ## Related * [Credits](/concepts/commerce/credits) * [Working with Credits](/dev-guides/commerce/working-with-credits) * [eCert issuance](/extensions/givex/ecert-issuance)