Log into Pro Sandbox

Crediting Cardholder Accounts

Suggest Edits

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, refer to the Card Transaction Scenarios.

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:

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.

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 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 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 CST and the Get All Transaction History 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 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 SETL: setl 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 CST and the Get All Transaction History 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 Merchant credit in Card Transaction Examples and for detailed examples see these scenarios:

Card loads

Card loads take place in one of two ways: over network rails and by other means. Loads over card rails (and their transaction codes) are:

  • Allpoint Cash Load (PMAO)
  • Mastercard Load (PMML)
  • Maestro Load (PMMX)
  • Visa ReadyLink (PMVL)
  • Visa Money Transfer (PMVH, PMVT)

These loads typically occur when the cardholder receives funds from a cash-transfer app such as Venmo or CashApp or is paid for their work with a gig-economy company such as Uber or DoorDash. (The exception is Visa ReadyLink, which permits cardholders to load cash on their cards at cash-accepting ATMs.) With Allpoint cash loads, the cardholder feeds cash directly into the ATM to load onto the card.

Galileo also supports loads from these other services, which you enable at the time you set up your program:

  • Western Union (PMSP)
  • Green Dot (PMGT)
  • MoneyGram (PMMG)

With these services, a cardholder enters a retail establishment and presents cash to a cashier, who transfers the cash onto the card. Galileo receives these transactions over special APIs, so they do not go over network rails. When reconciling your card transactions, do not include these transactions in any settlement totals. These transactions are present in the Posted Transactions RDF and the CST.

With other card-loading services such as push-to-card or remote deposit capture, the transactions are present in the Posted Transactions RDF and CST with the transaction codes that Galileo provides to you in your curated transaction code list.

Mastercard

Loads over Banknet or Maestro rails typically have an entry in the Authorized Transactions RDF that is expressed as a negative amount, even though it is a deposit. The corresponding settlement in the Posted Transactions RDF is a positive amount with the transaction code PMML (Mastercard Banknet rails) or PMMX (Maestro rails). The posting is available in Program API responses whereas the authorization is not.

For an example of a Maestro load, see Uber payment in Card Transaction Examples. For detailed examples of Maestro loads, see these card transaction scenarios:

Visa

For Visa loads the transaction does not have an entry in the Authorized Transactions RDF. The settlement is shown in the Posted Transactions RDF with transaction codes PMVL (Visa ReadyLink), PMVT or PMVH. The load is also available in Program API responses.

The Visa money transfer types are differentiated by the BAI. See the Business Application Identifier enumeration for the definitions.

  • PMVH — BP, CP, FD, GD, GP, LO, MD, OG, PD
  • PMVT — All other BAIs

Allpoint

Allpoint ATMs support inserting cash directly into the ATM and loading the amount onto the card. When the cash is inserted, the ATM sends an authorization request, which Galileo approves. As soon as the load is approved, the amount is credited to the cardholder account and is available to spend. The transactions are shown in the Posted Transactions RDF with the transaction code PMAO for loads and ADao for reversals.

Western Union

When a cardholder receives funds via Western Union, it is a card load with transaction code PMSP. Western Union uses a special API to send card loads to Galileo, so they do not go over network rails and there is no entry in the Authorized Transactions RDF. Use the source ID to track these transactions across Galileo systems.

However, when a cardholder sends funds using a service that runs over the Western Union infrastructure, the transaction follows the same authorization, backout, settlement sequence as a conventional card transaction.

Green Dot

Green Dot loads involve a cardholder presenting cash to an affiliated merchant, who loads the cash onto the card.

Green Dot communicates the loads to Galileo using a special API. Because these transactions do not arrive over card-network rails, there is no authorization request. The amount is visible in the Posted Transactions RDF with transaction code PMGT. (Green Dot direct deposits have transaction code PMGO.) Use the source ID to track these transactions across Galileo systems. You can also arrange with Galileo to receive special Events API webhooks for these loads.

Card load reversals

Card load reversals occur when a mistake was made with a card load, so it is reversed. For example, when a gig-economy company such as a grocery-delivery (e.g. Instacart) makes an error in paying out an employee and reserves the funds.

Card load reversals only take place over network rails. The transactions are present in the Posted Transactions RDF with the following transaction codes:

  • Maestro load reversal (ADMX)
  • Mastercard load reversal (ADq)
  • Visa ReadyLink load reversal (ADy)
  • Visa Direct OTC load reversal (ADyt)

These transactions are also present in the CST. For an example of a Maestro card load reversal, see Instacart deposit reversal in Card Transaction Examples. For a detailed example of a Maestro load reversal, see Scenario 20: Card Load Reversal (Maestro).

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.

Updated about 2 months ago