Crediting Cardholder Accounts

This guide explains transactions that move funds from the merchant to the cardholder account:

• Reversals — An authorization is negated fully or partially before clearing.
• Merchant credits — A transaction is reversed after clearing, or the merchant provides compensation to the cardholder.
• Card loads — Funds are deposited into the cardholder account.
• Disputes — A settled transaction is challenged with the help of the card network.

This guide assumes that you are familiar with the concepts in these guides:

• About Transactions — A general guide to how transactions are represented in the Galileo system.
• About Card Transactions — A general overview of how card transactions work, including the phases that a card transaction passes through.
• Authorization — A detailed explanation of authorization and its variants.
• Settlement — A detailed explanation of settlement and clearing.

📘

Note

To see detailed examples of transaction sequences as they appear in the Program API, Events API, Auth API, and RDFs, consult the Card Transaction Scenarios. Also consult Finding Transaction Data to see where transaction types are visible.

Reversals

A reversal negates all or part of a previous authorization. Reversals are performed before the transaction passes through the clearing stage and are performed in situations such as these:

• A preauthorization is for a larger amount than the final sale, so the remaining amount is reversed out.
• A transaction is performed in error, such as a duplicate transaction.
• A cardholder cancels a transaction in an app shortly after the initial authorization.
• A cardholder requests a refund for all or part of a purchase amount before the transaction clears.
• An e-commerce site gets a preauthorization for a nominal amount to verify the card, then reverses the amount before authorizing the full sale amount.
• The merchant does not receive an authorization response from the issuer.
• The merchant is unable to complete the authorized transaction because of technical problems.

A reversal may be for the previously authorized amount or for only part of it. When the reversal is for the same amount as the original authorization, the transaction is effectively canceled, so the merchant does not send a clearing message for that transaction. Instead of clearing, the authorization and its reversal expire out of the Galileo system after the configured time.

For most reversals, the transaction type is R, and the reversal ID (called the prior_id, original_id, and original_auth_id in other contexts) links the reversal with its authorization. For card-load reversals over network rails, the transaction type varies according to the network and the load type, and the prior_id is not necessarily populated. See the Transaction codes tables in the Transaction Types enumeration for reversal codes.

The sequence of events for a reversal is different depending on whether a full or partial amount is reversed. (In the explanations that follow, the MTI is provided for those clients who use the Auth API.)

Full reversal

When a merchant reverses all of a transaction before it clears, it's usually for one of these reasons:

• There was an error in making the original authorization request.
• A duplicate authorization request was accidentally sent.
• The authorization was for a small amount to check card status.
• A preauthorization was for an estimated amount that is followed by the actual sale amount soon after.
• The cardholder returned the item within a short time.

In this example reversal, the sale amount is $40.

1. The merchant sends an authorization request for -40.00, as either MTI 0100 or MTI 0200.
2. The authorization request is approved. Galileo assigns 4444 as the auth_id,sends the BAUT: auth webhook, and places a 40.00 hold on the account.
3. A few hours later, the merchant sends the reversal notification for 40.00 as MTI 0420. Because the third digit is 2, this is an advice, so only 00 is accepted as the response.
4. Galileo sends the webhook for the reversal with 5555 as the auth_id and 4444 as the original_id. Galileo sends the AAAU: auth webhook and removes the 40.00 hold.
5. These two transactions, the unsettled authorization (auth_id: 4444) and the reversal (auth_id: 5555), remain in Galileo's authorizations table until the configured expiry time for this transaction type and merchant.
6. At the expiry time, Galileo expires the two transactions from the database and sends the webhooks BEXP: auth_exp for auth_id: 4444 and BEXR: auth_exp_reversal for auth_id: 5555.
7. Neither of these two transactions will appear in the Posted Transactions RDF, but they will both be present in the Authorized Transactions RDF.

To see which transactions are produced by a reversal see Authorization reversal and expiry in Card Transaction Examples. For detailed examples see these card transaction scenarios:

• Scenario 4: Reversal on Authorization Before Clearing (Mastercard)
• Scenario 5: Reversal on Preauthorization Before Clearing (Visa)

Partial reversal

In some cases the merchant reverses out only part of the transaction before clearing, usually for these reasons:

• The cardholder returns only part of a purchase.
• The merchant made an error such as double-charging for an item.
• After a preauthorization, the merchant knows that the sale amount will be far less than the preauthorization amount, so it reverses out most of the preauthorization to release that amount from the authorization hold.

In this example reversal the initial sale amount is $80.

1. The merchant sends an authorization request for -80.00, as either MTI 0100 or MTI 0200.
2. You approve the request. Galileo assigns 3333 as the auth_id, sends the BAUT: auth webhook, and places an 80.00 hold on the account.
3. A little while later, the merchant sends a reversal notification for 30.00 as MTI 0420. Because the third digit is 2, this is an advice, so only 00 is accepted as the response.
4. Galileo sends the webhook for the reversal with 6666 as the auth_id and 3333 as the original_id. Galileo sends the AAAU: auth webhook and removes 30.00 from the hold.
5. A day or so later, the network sends a settlement file that contains the 50.00 transaction. Galileo expires the 30.00 reversal and sends the BEXR: auth_exp_reversal webhook.
6. Galileo matches the settlement to the auth_id: 3333 authorization, releases the 50.00 hold, posts -50.00 to the account, and then sends the SETL: setl webhook.
7. The original authorization request (auth_id: 3333) and the reversal (auth_id: 6666) will be present in the Authorized Transactions RDF but only the -50.00 settlement will be visible in the Posted Transactions RDF.

To see which transactions are produced by a partial reversal, see Partial reversal and expiry in Card Transaction Examples. For a detailed example see Scenario 8. Partial Reversal on Preauthorization.

Reversals and authorization limits

When a transaction is reversed out, it can affect authorization limits, depending on when the reversal happens. (The type of reversal referenced here has otype: R, meaning that it's an auth reversal instead of a refund after settlement or a merchant credit.)

• Reversal during the same period — Authorization limit is replenished
• Reversal during next period — Authorization limit is unaffected

In this example, the card has an auth limit of 600.00 per day.

• Row 1 — The cardholder makes a purchase of 200.00 on the 10th, which reduces the available auth limit to 400.00.
• Row 2 — The cardholder returns the item on the same day, and the merchant reverses out the authorization, which increases the auth limit by 200.00, returning it to 600.00.
• Row 3 — The cardholder makes a purchase of 450.00 on the 11th, which reduces that day's auth limit to 150.00.
• Row 4 — The cardholder returns the item on the 12th, and the merchant reverses out the authorization. Although the daily limit was reset to 600.00 earlier in the day, the 450.00 reversal does not increase the limit to 1050.00, because it did not take place on the same day as the original authorization.

For authorization limits that are applied per week or month, the same general rule applies: if the reversal occurs during the same period as the authorization, the reversal causes the corresponding auth limit to be replenished. A reversal occurring during the same week as the authorization will cause a weekly limit to increase, and a reversal occurring during the same month (or rolling 30-day period) as the authorization will cause a monthly auth limit to increase.

Merchant credits

A merchant credit is a transaction that moves funds from the merchant to the cardholder account. Merchant credits are provided in these types of circumstances:

• A cardholder returns a purchased item and requests a full or partial refund after the transaction has cleared, using the original card for the purchase.
• A cardholder returns a purchased item and requests a full or partial refund on a different card from the one used to make the purchase.
• A cardholder receives a gift and returns it to the original store.
• A cardholder is unhappy with services received, so the merchant provides credit as compensation.
• A cardholder disputes a settled transaction, and the merchant refunds the disputed amount.

For Mastercard Banknet (credit) merchant credits, the transaction is processed as an adjustment (trans_code: ADC); the other networks process merchant credits as card transactions with otype: Z.

When Galileo receives an authorization request for a merchant credit, it does not post the credit to the cardholder account at that time. The authorization may be included in the Authorized Transactions RDF, but the authorization does not change the available balance.

A few days later, when the settlement file arrives from the network, Galileo posts the credit to the cardholder account only if it doesn't exceed a certain threshold (usually $100). Credits above that threshold are sent to the Dispute team, which reviews each credit and then approves the credits that don't appear to be fraudulent. Upon approval, Galileo posts the credit to the cardholder account.

If you are maintaining your own ledger, and you receive a merchant credit request through the Auth API, do not post that amount to the cardholder account yet. Wait for the SETL: setl message with otype: Z (or for Mastercard credit the BADJ: adj message, otype: C) to post the credit to the account.

Alternatively, if you are handling disputes yourself, call the Get Pending Merchant Credits endpoint to retrieve all merchant credits that are awaiting approval, and then call Update Pending Merchant Credit to approve the credit and post it to the cardholder account.

Merchant credit after a purchase

When the cardholder returns all or part of a purchase after the merchant sent the clearing information to the network, the merchant provides merchant credit. This example shows the sequence of events for a purchase amount of $100 over any rails except Mastercard Banknet. (In this explanation, the MTI is provided for those clients who use the Auth API.)

1. The merchant sends an authorization request for -100.00, as either MTI 0100 or MTI 0200.
2. Galileo approves the request. Galileo assigns 7777 as the auth_id, sends the BAUT: auth webhook, and places a 100.00 hold on the account.
3. A day or so later, the network sends a settlement batch file that contains the -100.00 transaction. Galileo matches the settlement to the auth_id: 7777 authorization, releases the 100.00 hold, posts -100.00 to the account, and then sends the SETL: setl event message.
4. Some time later, the cardholder returns a $30 item and the merchant sends a merchant credit authorization request for 30.00 as either MTI 0120 or MTI 0220.
5. Galileo approves the merchant credit because it does not violate velocity limits. Galileo assigns 8888 as the auth_id. There is no value for the original ID and no event message is sent. The merchant credit is not added to the available balance at this time. The 30.00 merchant credit is visible in the Authorized Transactions RDF for that day.
6. A day or so later, the network sends a settlement batch file that contains the 30.00 credit. The credit does not exceed the $100 threshold, so Galileo can post it immediately. Because there is no matching entry in the authorizations table, Galileo creates a 30.00 authorization entry with auth_id: 8888, backs it out, and posts 30.00 to the account, and then sends the SETL: setl event message.
7. The 30.00 merchant credit is visible in the Posted Transactions RDF. The timestamp for the merchant credit in the RDFs corresponds to the time when Galileo received the merchant credit request, but the actual post date is visible in the CST, the Get All Transaction History endpoint response, and the SETL: setl event message.

Merchant credit without a purchase

A merchant may initiate a credit when a previous purchase was not made, such as when a cardholder returns a gift or any other time the merchant wants to compensate a cardholder, including resolving a dispute. This example shows the sequence of events for a merchant credit of $200 over any rails except Mastercard Banknet. (In this explanation, the MTI is provided for those clients who use the Auth API.)

1. The merchant sends a merchant credit authorization request for 200.00 as either MTI 0120 or MTI 0220.
2. Galileo approves the merchant credit because it does not violate velocity limits. Galileo assigns 9999 as the auth_id. The merchant credit is not added to the available balance at this time.
3. A day or so later, the network sends a settlement batch file that contains the 200.00 credit. Because the amount is above the $100 threshold, Galileo sends the transaction to the Dispute team for approval.
4. A day or so later, the Dispute team approves the merchant credit. Because there is no matching entry in the authorizations table, Galileo creates a 200.00 authorization entry with auth_id: 9999, backs it out, and posts 200.00 to the account, and then sends the SETL: setl event message.
5. The 200.00 merchant credit is visible in the Authorized Transactions RDF as well as the Posted Transactions RDF. The timestamp for the merchant credit in the RDFs corresponds to the time when Galileo received the merchant credit transaction, but the actual post date is visible in the CST, the Get All Transaction History endpoint response, and the SETL: setl event message.

Merchant credits from Mastercard Banknet

When the network is Mastercard Banknet, a merchant credit is processed as an adjustment, so Galileo does not create an authorization entry that is backed out. There is no entry in the Authorized Transactions RDF for the merchant credit.

For examples of merchant credits, see Merchant credit in Card Transaction Examples, and for detailed examples see these scenarios:

• Scenario 6. Refund after Clearing (Visa)
• Scenario 7. Refund after Clearing (Mastercard Banknet)

Card loads

A card load is a transaction by which funds are deposited directly into a card account, using the PAN as the "routing number" instead of a bank routing number (ACH, check) or a wire routing number. These loads are performed in a variety of contexts:

• Cash loads — The cardholder loads cash directly onto the card:
  • Retail outlet — With services such as GreenDot, Western Union, and Visa ReadyLink the cardholder presents cash at a store.
  • ATM — Specialized ATMs can receive cash or checks that the cardholder feeds into the machine, such as Allpoint or Visa Plus.
• Peer-to-peer — Also called "push to card." When receiving funds from a peer using a service such as Venmo or CashApp, the cardholder "cashes out" the funds to deposit them in the card account. This method is common for workers who are being paid by a gig-economy company such as Uber or DoorDash.

Card loads arrive at Galileo in one of two ways: over card network rails and via special APIs. This table indicates how each type of load arrives.

Card load transaction codes

See the Card load transaction codes table in the Transaction Types enumeration.

Viewing card loads

All card loads and their reversals are visible in the Posted Transactions RDF and the CST.

• Load reversals over Banknet or Maestro rails have an entry in the Authorized Transactions RDF that is expressed as a positive amount, even though it is a load reversal.
• Loads over Visa rails have an entry in the Authorized Transactions RDF that is expressed as a negative amount, even though it is a deposit.

When a card load arrives over card rails or via special API, it is immediately converted into a payment. In the response to Program API transaction-retrieval endpoints such as Get All Transaction History, the authorization is not present—only the payment is. The authorization is also not visible in the CST.

Card load event messages

Galileo sends these event messages in conjunction with card loads:

• BPMT: pmt — For all card loads, when the load is posted to the account.
• AAPM: auth_payment — Card loads that arrive over card-network rails. Sent at the same time as BPMT: pmt.
• GDAU: greendot_auth — Green Dot load authorization.
• GDAC: greendot_auth_commit — Green Dot authorization commit. Sent at the same time as BPMT: pmt.

Card load examples

Consult these examples:

• Simplified examples:
  • Uber payment
  • Instacart deposit reversal
• Detailed examples
  • Scenario 17: Card Load (Maestro)
  • Scenario 20: Card Load Reversal (Maestro)
  • Scenario 21: Card Load (Visa)
  • Scenario 22: Card Load Reversal (Visa)

Disputes

A cardholder has the right to challenge a transaction, such as when the transaction is unrecognized, when there is a duplicate transaction, or when the cardholder believes the amount is wrong. In the case of an account being driven negative, program managers also have the right to dispute transactions independently of the cardholder.

See About Disputes for information about the phases a dispute passes through. See also Disputes at Galileo for information specific to the Galileo implementation, including transaction codes and Events API webhook messages.

Events API webhooks

For reversals Galileo sends the AAAU: auth webhook. The value in amount is unsigned, so to detect a reversal, match the original_auth_id with a previous BAUT: auth webhook. For example, if you receive a BAUT: auth webhook with amount: 20 and auth_id: 3333, and then later you receive an AAAU: auth webhook with amount: 20 and original_auth_id: 3333, you know that it is a full reversal of the transaction.

For merchant credits over all networks except Mastercard Banknet, Galileo sends the SETL: setl webhook with otype: Z.

For Mastercard Banknet merchant credits, Galileo sends the BADJ: adj webhook with act_type: AD and otype: C.