Log into Sandbox

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:

  • <a href="doc:about-transactions" target="_blank">**About Transactions**</a> — A general guide to how transactions are represented in the Galileo system.

  • <a href="doc:about-card-transactions" target="_blank">**About Card Transactions**</a> — A general overview of how card transactions work, including the phases that a card transaction passes through.

  • <a href="doc:authorization" target="_blank">**Authorization**</a> — A detailed explanation of authorization and its variants.

  • <a href="doc:settlement" target="_blank">**Settlement**</a> — 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 <<glossary:RDF>>s, refer to the <a href="page:card-transaction-scenarios-index" target="_blank">Card Transaction Scenarios</a>.

## 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 <a href="ref:api-reference-transaction-types#transaction-codes" target="_blank">Transaction codes</a> 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 <<glossary: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 <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> 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 <a href="ref:api-reference-events-api-auth" target="_blank">`AAAU: auth`</a> 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 <a href="ref:api-reference-events-api-auth-exp" target="_blank">`BEXP: auth_exp`</a> for `auth_id: 4444` and <a href="ref:api-reference-events-api-auth-exp-reversal" target="_blank">`BEXR: auth_exp_reversal`</a> 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 <a href="doc:card-transaction-examples#authorization-reversal-and-expiry" target="_blank">Authorization reversal and expiry</a> in _Card Transaction Examples_. For detailed examples see these card transaction scenarios:

  • <a href="page:scenario-4-reversal-on-authorization-before-clearing-mastercard" target="_blank">Scenario 4: Reversal on Authorization Before Clearing (Mastercard)</a>

  • <a href="page:scenario-5-reversal-on-preauthorization-before-clearing-visa" target="_blank">Scenario 5: Reversal on Preauthorization Before Clearing (Visa) </a>

### 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 <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> 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 <a href="ref:api-reference-events-api-auth" target="_blank">`AAAU: auth`</a> 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 <a href="ref:api-reference-events-api-auth-exp-reversal" target="_blank">`BEXR: auth_exp_reversal`</a> 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 <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> 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 <a href="doc:card-transaction-examples#partial-reversal-and-expiry" target="_blank">Partial reversal and expiry</a> in _Card Transaction Examples_. For a detailed example see <a href="page:scenario-8-partial-reversal-on-preauthorization" target="_blank">Scenario 8. Partial Reversal on Preauthorization</a>.

## 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.

In all of these cases the cardholder contacts the merchant directly to ask for a refund instead of using the disputes process.

Merchant credits differ by network.

  • **Mastercard Banknet** — The merchant credit is not accompanied by an authorization and is posted as an adjustment.

  • **All other networks** — The merchant credit has an authorization for a positive amount that is later settled.

Merchant credits are posted at the time of settlement, not when an authorization arrives, if any, so a cardholder's available balance does not reflect a merchant credit until a few days after it is initiated.

When a network sends a merchant credit authorization request to the issuer, the issuer verifies that the card is eligible to receive a refund—that it has not been reported lost or stolen, for example, or that the credited amount does not violate load limits.

### 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 <<glossary: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 <a href="ref:api-reference-events-api-auth" target="_blank">`BAUT: auth`</a> 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 <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> webhook.

  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 webhook sent. The merchant credit is not added to the available balance at this time.

  6. A day or so later, the network sends a settlement batch file that contains the 30.00 credit. 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` webhook.

  7. The 30.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, which is later, is visible in the <<glossary:CST>> and the <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a> endpoint response.

### 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. This example shows the sequence of events for a merchant credit of $200 over any rails except Mastercard Banknet. (In this explanation, the <<glossary: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 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 <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> webhook.

  4. 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, which is later, is visible in the <<glossary:CST>> and the <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a> endpoint response.

#### 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 see <a href="doc:card-transaction-examples#merchant-credit" target="_blank">Merchant credit</a> in _Card Transaction Examples_ and for detailed examples see these scenarios:

  • <a href="page:scenario-6-refund-after-clearing-visa" target="_blank">Scenario 6. Refund after Clearing (Visa)</a>

  • <a href="page:scenario-7-refund-after-clearing-mastercard-banknet" target="_blank">Scenario 7. Refund after Clearing (Mastercard Banknet)</a>

## 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.

<!-- add <br>Visa Plus shared deposit to the visa cell no earlier than end of Aug 2023 -->

Load typeRails
Mastercard loadMastercard Banknet (credit)
Maestro loadMastercard Maestro (debit)
Visa Money Transfer<br>Visa ReadyLinkVisa (credit)
Allpoint cash loadAllpoint (ATM)
Western UnionSpecial API
Green DotSpecial API
MoneyGramSpecial API

### Card load transaction codes

See the <a href="ref:api-reference-transaction-types#card-load-transaction-codes" target="_blank">Card load transaction codes</a> table in the _Transaction Types_ enumeration.

### Viewing card loads

All card loads and their reversals are visible in the Posted Transactions RDF and the <<glossary:CST>>. Loads over Banknet or Maestro rails also 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 <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a>, 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:

  • <a href="ref:api-reference-events-api-pmt" target="_blank">`BPMT: pmt`</a> — For all card loads, when the load is posted to the account.

  • <a href="ref:api-reference-events-api-auth-payment" target="_blank">`AAPM: auth_payment`</a> — Card loads that arrive over card-network rails. Sent at the same time as `BPMT: pmt`.

  • <a href="ref:api-reference-events-api-greendot-auth" target="_blank">`GDAU: greendot_auth`</a> — Green Dot load authorization.

  • <a href="ref:api-reference-events-api-greendot-auth-commit" target="_blank">`GDAC: greendot_auth_commit`</a> — Green Dot authorization commit. Sent at the same time as `BPMT: pmt`.

### Card load examples

For examples of card loads, consult these examples:

  • Simplified examples:

    • <a href="doc:card-transaction-examples#uber-payment" target="_blank">Uber payment</a>

    • <a href="doc:card-transaction-examples#instacard-deposit-reversal" target="_blank">Instacart deposit reversal</a>

  • Detailed examples

    • <a href="page:scenario-17-card-load-maestro" target="_blank">Scenario 17: Card Load (Maestro)</a>

    • <a href="page:scenario-20-card-load-reversal-maestro" target="_blank">Scenario 20: Card Load Reversal (Maestro)</a>

## 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 <a href="doc:about-disputes" target="_blank">About Disputes</a> for information about the phases a dispute passes through. See also <a href="doc:disputes-at-galileo" target="_blank">Disputes at Galileo</a> for information specific to the Galileo implementation, including transaction codes and Events API webhook messages.

## Events API webhooks

For reversals Galileo sends the <a href="ref:api-reference-events-api-auth" target="_blank">`AAAU: auth`</a> 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 <a href="ref:api-reference-events-api-setl" target="_blank">`SETL: setl`</a> webhook with `otype: Z`.

For Mastercard Banknet merchant credits, Galileo sends the <a href="ref:api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> webhook with `act_type: AD` and `otype: C`.