Events API Scenarios

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

Event designation

Events in the documentation are represented by the msg_id, a unique four-letter code, and the type, which is the name of the event in snake_case.

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 Account Events Webhook.

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 Create Account endpoint populated with customer data and account enrollment is successful.
2. Galileo sends the CAPP: app_completed event to indicate that the enrollment application was completed.

Event

See Creating an Account 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 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 BFID: failed_id 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 PTID: pass_id event to indicate that the customer passed the integrated CIP process and the new account was created.

Events

📘

Note

If TIDST is set and the customer fails Galileo’s integrated CIP, Galileo sends the FTID: fail_id 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:
   • PCHG: profile_changed
   • ADRC: addr_chg
   • ECHG: email_addr_change
   • PHCH: phone_changed

Events

📘

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. The cardholder activates the card, according to your setup. See Card activation in Setting Up a Card Program for information about activation options. The card status changes to status: N.
2. Galileo sends the BACT: card_activated event.
3. The cardholder requests to set or change a PIN. See PIN Set Procedures for the different methods.
4. Depending on the method, Galileo sends the AFPS: agserv_PIN_change_success event to indicate that the PIN change was successfully staged.
5. You validate and commit the PIN change.
6. Galileo sends the PNCH: system_pin_change event to indicate that the PIN change completed successfully.

Events

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 Modify Status endpoint with type: 3 and the card status changed to status: L.
3. Galileo sends the CSNT: card_status_change event to indicate that the card status has changed.

Event

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 Modify Status endpoint with type: 17 to set the card to freeze_info: frozen (this does not change the card status).
2. Galileo sends you the FRZN: frozen 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 UFRZ: unfrozen event.

Events

Overdraft accounts

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

• ODIN: overdraft_opt_in indicates that the account became eligible for overdraft or that an overdraft account was created.
• ODOT: overdraft_opt_out indicates that the account lost overdraft functionality.

The ODIN: overdraft_opt_in event is usually triggered during account creation by the Create Account endpoint (if ODELG is set), or by the Add Account 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 Set Account Feature endpoint or through the CST. You can restore overdraft functionality and trigger ODIN: overdraft_opt_in via the CST. See Creating an Overdraft Account 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.

Event

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.

Event

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 Authorization Events Webhook.

The following sections describe some common scenarios that trigger authorization events. See also About Card Transactions 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 BAUT: auth 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 SETL: setl event.

Events

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 DAUT: denied_auth event. The account balance does not change.

Event

📘

Note

Specific events for denied authorization are:

• PUMP: denied_auth_gas
• NACT: denied_auth_inactive_card
• IPIN: denied_auth_invalid_pin
• BNSF: denied_auth_nsf
• BPAN: bad_pan

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 BAUT: auth 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 AAAU: auth event. The account balance is now 500.00.
7. The authorization and reversal expire after a few days. Galileo sends you the BEXP: auth_exp and BEXR: auth_exp_reversal events.

Events

📘

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 BAUT: auth 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 AAAU: auth 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 SETL: setl event.

Events

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 SETL: setl event message using the Settlement Events Webhook. You can ask Galileo to send you settlement events in a secondary queue (see Events prioritization 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 Reconciliation and settlement 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 SETL: setl event. The account balance is now 40.00.

Event

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 Transaction Events Webhook.

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

Basic billpay request

For more information on billpay transactions, see About Bill Pay.

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 Create Bill Payment endpoint, initiating the bill pay request.
3. Galileo creates the transaction and sends the BPCQ: billpay_request_made event message.
4. The billpay process adjusts the funds out of the account. The account balance is now 450.00. Galileo sends you the BPAY: billpay 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 BRRJ: billpay_rejected event message.

Events

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 Create Bill Payment endpoint and set the proccessDate field to the date that the amount should be adjusted from the account. Galileo sends the BPCQ: billpay_request_made event message
3. On the date that the bill payment is scheduled, Galileo adjusts the amount from the account and sends the BPAY: billpay 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 BPCM: billpay_check_mailed event.
5. Some days later, the recipient deposits the check and the payment clears.
6. Galileo sends you the BPCC: billpay_check_cleared event.

Events

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 Create ACH Transaction 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 ACRT: ach_return 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 BADJ: adj event.

Events

See the About ACH 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 Create Hold endpoint.
3. Galileo places a hold on 50.00 in the account and sends you the CRHD: create_hold event. The account balance is now 450.00.
4. The recipient does not process the payment and the hold expires.
5. You send the Expire Hold endpoint.
6. Galileo releases the hold on the funds and sends you the EXHD: expire_hold event. The account balance is now 500.00.

Events