There are four event categories in the Events API. Each category corresponds to a set of Events API webhooks. This guide describes each category and provides example scenarios that could trigger common events.

• [Account events](🔗)

• [Authorization events](🔗)

• [Settlement events](🔗)

• [Transaction events](🔗)

## Account events

An account event is triggered when an event occurs on a customer account, for example, when an account is created or updated, or when a card is activated. When an account event is triggered, Galileo sends you the event message using the <a href="ref:account-events-webhook" target="_blank">Account Events Webhook</a>.

The following sections describe some common scenarios that trigger account events.

### Account creation

This scenario describes an Events API webhook sequence that may occur when a new account is created.

1. You send the <a href="ref:post_createaccount" target="_blank">Create Account</a> endpoint populated with customer data and account enrollment is successful.

2. Galileo sends the <a href="ref:api-reference-events-api-app-completed" target="_blank">`CAPP: app_completed`</a> event to indicate that the enrollment application was completed.

#### Events API webhook

See <a href="doc:create-account-procedure" target="_blank">Creating an Account</a> for the complete account creation procedure.

### Account creation with failed CIP (when Galileo performs CIP)

This scenario describes an Events API webhook sequence that may occur when the customer fails Galileo’s internal <<glossary:CIP>> verification but later provides additional documentation and passes CIP.

1. A customer attempts to enroll in your program, but fails Galileo’s integrated CIP process.

2. Galileo sends the <a href="ref:api-reference-events-api-failed-id" target="_blank">`BFID: failed_id`</a> event to indicate that the customer failed the integrated CIP process and the account was not created.

3. Your customer provides additional documentation and you pass the customer for enrollment via the Program API or the CST. The account changes to status: N and active: Y.

4. Galileo sends the <a href="ref:api-reference-events-api-pass-id" target="_blank">`PTID: pass_id`</a> event to indicate that the customer passed the integrated CIP process and the new account was created.

#### Events API webhooks

📘

Note

If TIDST is set and the customer fails Galileo’s integrated CIP, Galileo sends the <a href="ref:api-reference-events-api-fail-id" target="_blank">`FTID: fail_id`</a> event and the account changes to the status in TIDST.

### Updating account information

This scenario describes an Events API webhook sequence that may occur when account information is updated in the Customer Service Tool.

1. You update the customer’s first name, address, phone number, and email address in the CST Account Info screen.

2. Galileo sends the following events:

   • <a href="ref:api-reference-events-api-profile-changed" target="_blank">`PCHG: profile_changed`</a>

   • <a href="ref:api-reference-events-api-addr-chg" target="_blank">`ADRC: addr_chg`</a>

   • <a href="ref:api-reference-events-api-email-addr-change" target="_blank">`ECHG: email_addr_change`</a>

   • <a href="ref:api-reference-events-api-email-addr-change" target="_blank">`PHCH: phone_changed`</a>

#### Events API webhooks

📘

Note

If `ADRC: addr_chg`, `ECHG: email_addr_change`, and `PHCH: phone_changed` are not configured, Galileo sends `PCHG: profile_changed` for address, email, and phone number changes.

### Card activation and PIN setting

This scenario describes an Events API webhook sequence that may occur when a card is activated and the PIN is set.

1. You activate a card for a cardholder. The card status changes to `status: N`.

2. Galileo sends the <a href="ref:api-reference-events-api-card-activated" target="_blank">`BACT: card_activated`</a> event.

3. The cardholder requests a PIN change and enters a valid PIN in the PIN-change form.

4. Galileo sends the <a href="ref:api-reference-events-api-agserv-pin-change-success" target="_blank">`AFPS: agserv_PIN_change_success`</a> event to indicate that the PIN change was successfully staged.

5. You validate and commit the PIN change.

6. Galileo sends the <a href="ref:api-reference-events-api-system-pin-change" target="_blank">`PNCH: system_pin_change`</a> event to indicate that the PIN change completed successfully.

#### Events API webhooks

See <a href="doc:activate-card-procedure" target="_blank">Activating a Card</a> and <a href="doc:pin-set-procedures" target="_blank">PIN Set Procedures</a> for more information on these processes.

### Card status changes

During product setup, you can configure the CDMSG parameter to specify which card status changes will trigger the `CSNT: card_status_change` event. For example, you might set CDMSG to trigger this event message when the card status changes to lost (`status: L`) or stolen (`status: S`). In that case, the following Events API webhook sequence may occur.

1. The cardholder reports that the card was lost.

2. You send the <a href="ref:post_modifystatus" target="_blank">Modify Status</a> endpoint with `type: 3` and the card status changed to` status: L`.

3. Galileo sends the <a href="ref:api-reference-events-api-card-status-change" target="_blank">`CSNT: card_status_change`</a> event to indicate that the card status has changed.

#### Events API webhook

### Freezing and unfreezing a card

This scenario describes an Events API webhook sequence that may occur when a card is frozen and then unfrozen.

1. You send the <a href="ref:post_modifystatus" target="_blank">Modify Status</a> endpoint with `type: 17` to set the card to `freeze_info: frozen` (this does not change the card status).

2. Galileo sends you the <a href="ref:api-reference-events-api-frozen" target="_blank">`FRZN: frozen`</a> event.

3. Later, you unfreeze the card by sending the Modify Status endpoint with `type: 18` to set the card to `freeze_info: unfrozen`.

4. Galileo sends you the <a href="ref:api-reference-events-api-unfrozen" target="_blank">`UFRZ: unfrozen`</a> event.

#### Events API webhook

### Overdraft accounts

There are two event messages that can be triggered when an account gains or loses overdraft functionality.

• <a href="ref:api-reference-events-api-overdraft-opt-in" target="_blank">`ODIN: overdraft_opt_in`</a> indicates that the account became eligible for overdraft or that an overdraft account was created.

• <a href="ref:api-reference-events-api-overdraft-opt-out" target="_blank">`ODOT: overdraft_opt_out`</a> indicates that the account lost overdraft functionality.

The `ODIN: overdraft_opt_in` event is usually triggered during account creation by the <a href="ref:post_createaccount" target="_blank">Create Account</a> endpoint (if ODELG is set), or by the <a href="ref:post_addaccount" target="_blank">Add Account</a> endpoint when the overdraft account is added. It can also be triggered during enrollment via the CST or Galileo-hosted cardholder website.

The `ODOT: overdraft_opt_out` event can be triggered by the <a href="ref:post_setaccountfeature" target="_blank">Set Account Feature</a> endpoint or through the CST. You can restore overdraft functionality and trigger `ODIN: overdraft_opt_in` via the CST. See <a href="doc:creating-an-overdraft-account" target="_blank">Creating an Overdraft Account</a> for more information on this process.

**Overdraft opt-in:** This scenario describes an Events API webhook sequence that may occur when an overdraft account is added to an existing core account.

1. You send the Add Account endpoint to create the overdraft account.

2. Galileo sends you the `ODIN: overdraft_opt_in` event.

#### Events API webhooks

**Overdraft opt-out:** This scenario describes an Events API webhook sequence that may occur when an account with overdraft functionality becomes ineligible for the overdraft account.

1. You send the Set Account Feature endpoint with `featureType: 17` and `featureValue: I`.

2. Galileo sends you the `ODOT: overdraft_opt_out` event.

#### Events API webhooks

## Authorization events

An authorization event is triggered when a cardholder makes a transaction over card-network rails and the transaction is authorized or the authorization is denied. When an authorization event is triggered, Galileo sends you the event message using the <a href="ref:authorization-events-webhook" target="_blank">Authorization Events Webhook</a>.

The following sections describe some common scenarios that trigger authorization events. See also <a href="doc:about-card-transactions" target="_blank">About Card Transactions</a> for more information on card authorization.

### Basic authorization and settlement

For basic authorization and settlement, Galileo sends two events: one for authorization and one for settlement.

This scenario describes an Events API webhook sequence that may occur when a transaction is authorized and then settled.

1. Your customer has an account balance of $500. The customer makes a retail purchase for $25.00 over card-network rails.

2. The card network sends an authorization request for -25.00.

3. Galileo approves the request and places a 25.00 hold on the account. Galileo sends you the <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> event. The account balance is now 475.00

4. The card network sends a batch file with the -25.00 transaction.

5. Galileo backs out the 25.00 hold and posts -25.00 to the account. Galileo sends you the <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> event.

#### Events API webhooks

### Authorization denied

This scenario describes an Events API webhook sequence that may occur when an authorization request is denied.

1. Your customer has an account balance of $500. The customer attempts to make a retail purchase for $10 over card-network rails.

2. The card network sends an authorization request for -10.00.

3. Galileo denies the authorization but the denial is not covered by a specific event message. Galileo sends you the <a href="ref:api-reference-events-api-denied-auth" target="_blank">`DAUT: denied_auth`</a> event. The account balance does not change.

#### Events API webhooks

📘

Note

Specific events for denied authorization are:

• <a href="ref:api-reference-events-api-denied-auth-gas" target="_blank">`PUMP: denied_auth_gas`</a>

• <a href="ref:api-reference-events-api-denied-auth-inactive-card" target="_blank">`NACT: denied_auth_inactive_card`</a>

• <a href="ref:api-reference-events-api-denied-auth-invalid-pin" target="_blank">`IPIN: denied_auth_invalid_pin`</a>

• <a href="ref:api-reference-events-api-denied-auth-nsf" target="_blank">`BNSF: denied_auth_nsf`</a>

• <a href="ref:api-reference-events-api-denied-auth-bad-pan" target="_blank">`BPAN: bad_pan`</a>

### Authorization with reversal and expiry

This scenario describes an Events API webhook sequence that may occur when an authorization is reversed and then expires.

1. Your customer has an account balance of $500. The customer makes a retail purchase for $40 over card-network rails.

2. The card network sends an authorization request for -40.00.

3. Galileo approves the request and places a 40.00 hold on the account. Galileo sends you the <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> event. The account balance is now 460.00

4. The cardholder cancels the transaction before it clears.

5. The card network sends an authorization request for 40.00, reversing the previous authorization.

6. Galileo reverses the 40.00 hold on the account. Galileo sends you the <a href="ref:api-reference-events-api-auth" target="_blank">`AAAU: auth`</a> event. The account balance is now 500.00.

7. The authorization and reversal expire after a few days. Galileo sends you the <a href="ref:api-reference-events-api-auth-exp" target="_blank">`BEXP: auth_exp`</a> and <a href="ref:api-reference-events-api-auth-exp-reversal" target="_blank">`BEXR: auth_exp_reversal`</a> events.

#### Events API webhooks

📘

Note

Galileo sends the `BAUT` event for an initial authorization request and the `AAAU` event for an authorization reversal.

### Preauthorization with completion

A card network can send a preauthorization request with an upcharge that covers the expected amount of a purchase. Then, when the total amount is known, the card network can send a completion advice message with the total amount.

This scenario describes an Events API webhook sequence that may occur when a transaction results in preauthorization with completion.

1. A debit cardholder goes to a gas station and begins pumping gas. The cardholder has an account balance of $500. The issuer has configured an upcharge of $100 for gas pumps.

2. The gas merchant sends a preauthorization request for -1.00.

3. Galileo replaces the 1.00 request with a 100.00 preauthorization, approves the request and places a 100.00 hold on the account. The account balance is now 400.00. Galileo sends you the <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> event.

4. The cardholder finishes pumping gas and the total amount is $20.00. The card network sends a completion advice for -20.00.

5. Galileo backs out the 100.00 hold and replaces it with a 20.00 hold. The account balance is now 480.00. Galileo sends you the <a href="ref:api-reference-events-api-auth" target="_blank">`AAAU: auth`</a> event.

6. The card network sends a settlement file with the -20.00 transaction.

7. Galileo backs out the 20.00 hold and posts -20.00 to the account. Galileo sends you the <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> event.

#### Events API webhooks

## Settlement events

A settlement event is triggered when a transaction made over card-network rails is settled on an account. Galileo receives daily batch files from the card networks that contain clearing information for each transaction. Galileo compares the transactions in the batch file with the authorizations it has on record. When Galileo finds a match, it posts the amount to the cardholder account and sends you the <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> event message using the <a href="ref:settlement-events-webhook" target="_blank">Settlement Events Webhook</a>. You can ask Galileo to send you settlement events in a secondary queue (see <a href="doc:events-setup-and-configuration#events-prioritization" target="_blank">Events prioritization</a> in _Events Setup and Configuration_ for more information).

📘

Note

For `SETL: setl` events, you can request the `signed_amount` field to be added to your message template to help you distinguish between credit and debit settlements.

The following sections describe some common scenarios that trigger settlement events.

### Basic settlement

A basic settlement occurs when a transaction is authorized and then settled. See [Basic authorization and settlement](🔗) for an example.

### Force posting

If Galileo cannot match a transaction in the settlement file to an authorization, Galileo is obligated to post the settlement anyway. Depending on the reason that the transaction is unmatched, Galileo or the cardholder can dispute the transaction. See <a href="doc:about-card-transactions#4-reconciliation-and-settlement" target="_blank">Reconciliation and settlement</a> in the _About Card Transactions_ guide for an explanation of unmatched settlement types.

This scenario describes an Events API webhook sequence that may occur when a transaction is force-posted without authorization.

1. Your customer has an account balance of $50. The customer makes a $10 purchase at a fast food restaurant over card-network rails.

2. To keep the line moving quickly, the restaurant does not make an authorization request, but instead sends a batch force-post request to the card network..

3. The card network sends a clearing message advising that the merchant intends to settle on the amount. Galileo posts -10.00 to the account and sends you the <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> event. The account balance is now 40.00.

#### Events API webhook

## Transaction events

A transaction event is triggered when a transaction that does not go over card-network rails is made on an account. Examples include bill payments, fees, adjustments, and ACH transactions. When a transaction event is triggered, Galileo sends you the event message using the <a href="ref:transaction-events-webhook" target="_blank">Transaction Events Webhook</a>.

The following sections describe some common scenarios that trigger transaction events.

### Basic bill pay request

This scenario describes an Events API webhook sequence that may occur when a bill payment is made.

1. Your customer has an account balance of $500. The customer requests to make a bill payment for $50 through an RPPS biller that has already been added to the account.

2. You send the <a href="ref:post_createbillpayment" target="_blank">Create Bill Payment</a> endpoint, initiating the bill pay request.

3. Galileo creates the transaction and sends the <a href="ref:api-reference-events-api-billpay-request-made" target="_blank">`BPCQ: billpay_request_made`</a> event message.

4. The billpay process adjusts the funds out of the account. The account balance is now 450.00. Galileo sends you the <a href="ref:api-reference-events-api-billpay" target="_blank">`BPAY: billpay`</a> event message.

5. The RPPS biller receives the payment (depending on the cutoff time, this is often the next day). Galileo is not notified when the transaction is successful. If the payment is rejected, Galileo sends the <a href="ref:api-reference-events-api-billpay-rejected" target="_blank">`BRRJ: billpay_rejected`</a> event message.

#### Events API webhooks

### Scheduled bill payment with paper check

This scenario describes an Events API webhook sequence that may occur when a bill payment is scheduled and the payment is sent as a paper check.

1. Your customer requests a monthly bill payment for $35 to be made with a paper check.

2. You send the <a href="ref:post_createbillpayment" target="_blank">Create Bill Payment</a> endpoint and set the `proccessDate` field to the date that the amount should be adjusted from the account. Galileo sends the <a href="ref:api-reference-events-api-billpay-request-made" target="_blank">`BPCQ: billpay_request_made`</a> event message

3. On the date that the bill payment is scheduled, Galileo adjusts the amount from the account and sends the <a href="ref:api-reference-events-api-billpay" target="_blank">`BPAY: billpay`</a> event message. There is now 465.00 in the account.

4. On the next business day, Galileo prints and mails the paper check. Galileo sends you the <a href="ref:api-reference-events-api-billpay-check-mailed" target="_blank">`BPCM: billpay_check_mailed`</a> event.

5. Some days later, the recipient deposits the check and the payment clears.

6. Galileo sends you the <a href="ref:api-reference-events-api-billpay-check-cleared" target="_blank">`BPCC: billpay_check_cleared`</a> event.

### Outgoing ACH debit with return

This scenario describes an Events API webhook sequence that may occur when your customer sends an outgoing ACH debit request to move money out of an external account and the external receiver denies the request.

1. Your customer has an account balance of $500. The customer creates an ACH debit request to move $100 out of an external account and into the cardholder account.

2. You send the <a href="ref:post_createachtransaction" target="_blank">Create ACH Transaction</a> endpoint.

3. After the configured number of ACH hold days has elapsed, Galileo posts a payment (`pmt_type: AC`) of 100.00 into your customer’s account. The account balance is now 600.00.

4. The external receiver denies the ACH transaction and an ACH return is initiated.

5. Galileo sends you the <a href="ref:api-reference-events-api-ach-return" target="_blank">`ACRT: ach_return`</a> event (the NTSAA parameter must be set to enable this event).

6. Galileo adjusts the cardholder account by -100.00. The account balance is now 500.00. Galileo sends you the <a href="ref:api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> event.

#### Events API webhooks

See the <a href="doc:about-ach" target="_blank">About ACH</a> guide for general information on ACH transactions.

### Holds and lifting holds

📘

Note

This scenario applies to holds placed on non-card network transactions. A hold placed on a transaction over card network rails is a separate and automatic process. See [Authorization events](🔗) in this guide for information on events that apply to card network transactions.

This scenario describes an Events API webhook sequence that may occur when a customer sends a check via remote deposit capture (RDC), you place a hold on the funds in the customer account and then later lift the hold.

1. Your customer has an account balance of $500. The customer sends a check to a recipient for $50 using RDC. The funds must be held until the recipient processes the payment.

2. You send the <a href="ref:post_createhold" target="_blank">Create Hold</a> endpoint.

3. Galileo places a hold on 50.00 in the account and sends you the <a href="ref:api-reference-events-api-create-hold" target="_blank">`CRHD: create_hold`</a> event. The account balance is now 450.00.

4. The recipient does not process the payment and the hold expires.

5. You send the <a href="ref:post_expirehold" target="_blank">Expire Hold</a> endpoint.

6. Galileo releases the hold on the funds and sends you the <a href="ref:api-reference-events-api-expire-hold" target="_blank">`EXHD: expire_hold`</a> event. The account balance is now 500.00.

#### Events API webhooks