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 RDFRDF - Raw data file. Once per day Galileo sends you RDFs that contain a list of all of your previous day's transactions and all of your current customers. Compare the RDFs with your own records and if there are discrepancies, treat the RDFs as authoritative.s, ask for the Card Transaction Scenarios PDF from Galileo.

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.
  • 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 all 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.

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 MTIMTI - Message type identifier. ISO 8583 specifies the format for messages that traverse card-network rails. The MTI identifies the message as an authorization request, authorization response, reversal, reconciliation (settlement), and so on. 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 scenarios in the Card Transaction Scenarios PDF:

  • 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</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 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" in the Card Transaction Scenarios PDF.

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 MTIMTI - Message type identifier. ISO 8583 specifies the format for messages that traverse card-network rails. The MTI identifies the message as an authorization request, authorization response, reversal, reconciliation (settlement), and so on. 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 CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view and manage customers and their accounts. 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 MTIMTI - Message type identifier. ISO 8583 specifies the format for messages that traverse card-network rails. The MTI identifies the message as an authorization request, authorization response, reversal, reconciliation (settlement), and so on. 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 CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view and manage customers and their accounts. 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 in the Card Transaction Scenarios PDF:

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

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:

  • 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.)

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 CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view and manage customers and their accounts..

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 a detailed example of a Maestro load, see "Scenario 17: Card load (Maestro load)" in the Card Transaction Scenarios PDF.

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 (Visa Money Transfers, with different load limits set by Visa). The load is also available in Program API responses.

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

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.

Only a settled transaction can be disputed—for a pending authorization, the cardholder should contact the merchant and attempt to obtain a reversal. Alternatively, instead of initiating a dispute, a cardholder can contact the merchant directly and request merchant credit after settlement. Merchants are assessed special fees for chargebacks in addition to the standard transaction fees, and so they prefer to avoid chargebacks whenever possible.

It is also possible to return a merchant credit. In that case, the issuer or cardholder initiates a chargeback process to return it.

When you set up your program you determine whether Galileo will handle your disputes or whether you or a third-party provider will handle them.

Disputes pass through as many as three phases:

  • Chargeback — The dispute is initiated. The network returns the funds to you, and you may provisionally credit the cardholder account at this time, if desired.
  • Second presentment — The merchant presents evidence to the network, if any, that the transaction was legitimate. If the network determines that the dispute should resolve in the merchant's favor, the funds are removed from your account and returned to the network.
  • Arbitration or exception — If further evidence indicates that the dispute should be resolved differently, funds are moved accordingly, either to your account or to the network.

When Galileo is handling your disputes, the dispute-related transactions are processed as adjustments (activity type AD). The transaction types for these adjustments are in the Additional network transactions table of the Transaction Types enumeration. When calculating settlement totals, be sure to include these dispute-related transactions in the totals.

Dispute-related transactions arrive at Galileo in the bulk settlement file, not over the authorization stream, so there is no record in the Authorized Transactions RDF and they are not handled by the Auth API.

Every settled transaction has an acquirer reference number (ARN) that can be used when disputing a transaction. The ARN is available in the CST, the Program API responses, and by request in the Posted Transactions RDF.

To see an example of a disputed transaction see Disputes in Card Transaction Examples.

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, the SETL: setl webhook has act_type: AD and otype: C, and Galileo also sends the BADJ: adj webhook with the same auth_id as the SETL: setl webhook.

For dispute-related transactions Galileo sends the BADJ: adj webhook with otype containing the dispute-related value in the Additional network transactions table of the Transaction Types enumeration. For BADJ: adj webhooks, the amount is signed, so you know which way the funds flow.

To see examples of transaction sequences with Events API webhooks, see Authorization events in the Events API Scenarios guide.


Did this page help you?