Skip to main content
This page gives a high-level overview of the core concepts behind ledger management for card-based transactions at Marqeta. After reading this guide, you should understand:
  • The different types of funding and network messages, and when they are used.
  • Best practices for ledger management with single- and dual-message transactions.
  • JIT Funding transaction flows for dual-message and single-message transactions.
  • The impact of funding and network messages on ledger management.
  • How to associate events using tokens and webhooks.
  • The impact of timeouts and other errors on ledger management.
Note
This guide covers ledger management when using JIT Funding. If your program uses standard funding, you can see the real-time balance of GPA ledgers by sending a GET request to the /balances endpoint. For details, see the Balances API reference.

​
Funding and network message values

The following values in funding and network messages are helpful when making a JIT decision related to funding a transaction and adjusting the ledger. They apply to both dual- and single-message transaction:
FieldDescription
gpa_order.jit_funding.amountJIT Funding requests contain several fields with different amounts. When considering whether or not to approve a transaction, you can use the value in the gpa_order.jit_funding.amount field to inform your decision, as this value contains the amount that must be funded if the transaction is to be approved.
impacted_amountMultiple amount fields are shown in webhooks. When you receive a webhook confirming a transaction, you can use the value shown in the impacted_amount attribute to adjust the ledger. Based on the transaction type, the attribute will indicate whether there is a positive or negative impact on the ledger.

​
Dual-message transactions

Dual-message transactions, such as requiring a signature during a card present transaction, have separate funding messages for authorization and other event types, and also require a clearing message to complete the transaction.
  • The initial funding message creates a pending transaction in the cardholder account.
  • An advice message contains additional information about the total amount of a pending transaction. When a merchant sends an advice message, the recipient must acknowledge the receipt of the advice message with an advice response message. See also the definition of advice on the Payment Cards Concepts page.
Clearing occurs when Marqeta receives and processes batch clearing records from the card network. Clearing records provide information about additional amounts that need to be processed with previously approved transactions. A dual-message transaction is considered complete after the clearing message is received. See also the definition of clearing on the Payment Cards Concepts page. A three-chain transaction is a type of dual-message transaction that sends separate messages for authorization, advice, and clearing. When the final amount of a pending transaction changes, an additional advice message within the same transaction is required before clearing can occur.

​
JIT Funding transaction flows

​
Approvals

This following sequence shows you a successful processing flow for a dual-message transaction that has been approved by your system.
1
Your system receives an actionable funding message from a merchant requesting authorization for a transaction on your JIT gateway endpoint.
2
Your system authorizes the transaction and sends a 200 JIT Funding approval response to the Marqeta platform.
3
Your system places a temporary hold on the cardholder’s available balance.
4
The Marqeta platform receives the JIT Funding approval response and processes the transaction.
5
The Marqeta platform sends a network message (in the form of a webhook) to your webhook endpoint, confirming successful processing of the transaction. The transaction will show as pending in the webhook status field, confirming that no issues occurred when processing the transaction that your system approved for funding.NOTE: The temporary hold on the cardholder’s available balance at the time of the JIT Funding approval response will remain in place until the clearing records are processed. Therefore, you do not need to make adjustments to ledger balances at this time.
6
The Marqeta platform later receives batch clearing records from the card network that contain information about the funds needed to clear the transactions that your system previously approved.
7
When the transaction has cleared, the Marqeta system will send a clearing network message as a webhook to the transaction.authorization.clearing endpoint.
8
At this time, your system completes the cash movement on the cardholder’s current balance by removing the temporary hold from their available balance.

​
Declines

1
Your system receives an actionable JIT Funding authorization request message (i.e., funding message) on your JIT gateway endpoint.
2
Your system declines the transaction and sends a 402 JIT Funding decline response to the Marqeta platform. At this time, you do not need to perform any ledger management.
3
The Marqeta platform sends a webhook, or network message, to the endpoint transaction.authorization to confirm that your system declined the transaction. The webhook will give the status of the transaction as declined.

​
Webhook authorization declines

In some cases, you might receive a network message (i.e., a webhook) indicating that the JIT Funding request has been declined even though you have approved the transaction. This can happen when there is a processing error either at Marqeta or with the card network. Declines can also occur when the approval from your system is not received within the required three-second interval and the transaction times out. In both of these situations, your system will place a temporary hold on the cardholder’s available balance, as the transaction was approved by your system prior to encountering the processing error. In these cases, you should remove the initial hold that was placed on the cardholder’s available balance to ensure that their purchasing power is not impacted by the declined transaction. For more information, see Timeouts below.

​
Single-message transactions

Single-message transactions use only one message, sent at the time of the transaction, to convey information about both authorization decisions and clearing. The majority of single-message transactions are either debit card or PIN transactions, also known as “pin debit” transactions.

​
Ledger management and JIT Funding messages

The ledger can be impacted when JIT Funding messages are received by your gateway endpoint.

​
Approval messages

When your gateway endpoint receives and approves an actionable pindebit JIT Funding request, your system sends a 200 funding approval message to Marqeta. When the funding approval message is sent, your system immediately places a temporary hold on the cardholder’s available balance for the amount of the transaction so that the ledger accurately reflects the cardholder’s purchasing power.

​
Decline messages

When your gateway endpoint receives an actionable pindebit JIT Funding request and responds with a 402 decline message, no ledger management is required, as it is your system that declined the funding request. You will receive a webhook from transaction.authorization confirming the decline, with declined as the webhook status.

​
Ledger management and network messages

Network messages (i.e., webhooks) are sent to your JIT gateway after Marqeta receives a response either approving or declining a transaction.

​
Webhook approvals

When Marqeta receives your JIT Funding approval message, the Marqeta platform begins processing the transaction. When transaction processing is complete, the card network relays a network webhook to your webhook endpoint at transaction.pindebit, confirming that the transaction has been successfully processed. The corresponding webhook will have a value of completed in the status field if there were no issues with the Marqeta platform or the card network during processing. Single-message transactions are considered to be completed when you receive the webhook confirmation. At that time, you should complete the movement of funds by removing the temporary hold from the cardholder’s available balance so that the amount of the transaction is deducted from the cardholder’s current balance.

​
Webhook declines

Occasionally, you might receive a network message (i.e., webhook) stating that Marqeta has declined a transaction even though you sent Marqeta a JIT Funding approval. This type of decline can happen when there is a processing error with either Marqeta or the card network, or if you did not send a response within the required three-second interval, resulting in a timeout. When this happens, you must reverse the temporary hold that you placed on the cardholder’s available balance to ensure that the cardholder’s purchasing power is not affected by the declined transaction.

​
Associating events

You can use tokens to associate transaction events over time. Associating events is particularly useful when you want to accurately manage or adjust cardholder balances after a dual-message or three-chain transaction. The two main types of tokens that you can use to correlate events are as follows:
Token TypeDescription
Preceding related transaction tokenUse this attribute to correlate a following event (for example, authorization.clearing) with its corresponding originating event, such as an authorization.

NOTE: Marqeta does not automatically associate events using the preceding_related_transaction_token for all transaction scenarios due to limited matching logic from the card networks. For more information, contact your Marqeta representative.
Original JIT Funding tokenThe first associated JIT Funding message creates a token that you can use to associate JIT Funding messages related to the initial message using the same GPA order.

This field is not included in the first of any set of related messages.

​
Timeouts

A timeout by your JIT gateway, the Marqeta platform, or the card network can impact transaction processing. For more information on how to handle this situation, see the Managing Timeouts guide.

​
JIT gateway timeouts

Transaction approvals can time out if Marqeta sends an approval response to your funding request outside of the constraints of the API’s duration. Use webhooks to confirm that the approval response from Marqeta has been recorded in the ledger as an approval, rather than a decline due to a timeout. Check the body of the webhook body for a value of true in the gateway_log.timed_out field to confirm that the JIT Funding request timed out.

​
Marqeta platform or card network timeouts

The following codes are examples of decline codes that you might receive if a processing error occurs with a Marqeta-specific application, or if there is a connectivity error with the card network. For the full list of supported decline codes, see Transaction response codes.
Decline CodeMessage
1878Corresponding JIT load failure.
1842Account load failed.
1844The card network has advised of a decline.

​
Account ledgers

An account ledger is the system of record that keeps track of all transactions that occur on a user or business account. It is important to keep an account ledger current as it provides an accurate record of money movement and balances needed to make real-time funding decisions. The level of ledger management the Marqeta platform provides depends on the type of funding model your program uses. For standard funding, Marqeta maintains general purpose account (GPA) ledgers. For JIT Funding, your business maintains its own account ledgers and updates them using transaction data Marqeta sends in JIT Funding messages. The following sections cover these topics:
  • How the three JIT Funding messages types relate to your ledger.
  • How to use information in JIT Funding messages to help manage your ledger.
  • Which transaction events impact the ledger.
  • Balances in JIT Funding responses.
  • Best practices for ledger maintenance.

​
JIT Funding message types

There are three types of JIT Funding messages that the Marqeta platform and your system exchange. For Gateway JIT, all three messages are exchanged. For Managed JIT, only JIT Funding notifications are sent.
  • JIT Funding requests – For Gateway JIT, the Marqeta platform sends these messages to your gateway endpoint to request permission to fund a transaction or to make a balance inquiry. These messages contain transaction data you can use to help manage your account ledgers.
  • JIT Funding responses – For Gateway JIT, your gateway sends these messages to the Marqeta platform in response to a funding request or balance inquiry. To accurately respond to a balance inquiry, your ledger must be current. For details, see Balances in Gateway JIT Funding responses later on this page.
  • JIT Funding notifications – For Gateway and Managed JIT, these are informative messages sent by the Marqeta platform to your webhook endpoint. These messages contain transaction data you can use to help manage your account ledgers.

​
Transaction data for ledger management

Certain transaction events impact your account ledgers. In these cases, you can update the account balances using the transaction data sent in JIT Funding messages to your gateway and webhook endpoints. For Gateway JIT, the JIT Funding message type, actionable or informative, does not indicate whether the transaction impacts the ledger, as both can. For details, see the Gateway JIT Funding Messages API reference.

​
Transaction event type

Use the type field to identify the transaction event type and whether it impacts the ledger. For a list of all transaction events that impact ledgers and how, see Ledger-impacting transaction events later on this page.

​
Impacted amount

The impacted amount represents the positive or negative amount a transaction impacts the ledger. Use the impacted_amount field, embedded in the gpa object, to determine the amount impacted and whether it is positive or negative. A minus symbol ( - ) indicates a negative impact. Update your account balances accordingly. The following code block shows a sample gpa object with a negative ledger impact of 10.00 USD as it would appear in a JIT Funding request or notification:
JSON
"gpa": {
  "currency_code": "USD",
  "ledger_balance": 20.00,
  "available_balance": 0.00,
  "credit_balance": 0.00,
  "pending_credits": 0.00,
  "impacted_amount": -10.00,
  "balances": {
    "USD": {
      "currency_code": "USD",
      "ledger_balance": 20.00,
      "available_balance": 0.00,
      "credit_balance": 0.00,
      "pending_credits": 0.00,
      "impacted_amount": -10.00
    }
  }
},

​
Amount

An amount field can appear in different objects representing different amount types. The amount field representing the transaction amount is embedded directly in the JIT Funding message as transaction.amount.

​
Method

The method represents the program gateway funding source (PGFS) method. Use the method field, embedded in the jit_funding object, to determine the JIT Funding method used. The following code block shows a sample JIT Funding request containing an authorization transaction of $10.00 that impacts the ledger by -10.00 USD:
JSON
{
  "type": "authorization",
  "state": "PENDING",
  "token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
  "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
  "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
  "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
  "network_reference_id": "0002469298452099894"
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 20.00,
    "available_balance": 0.00,
    "credit_balance": 0.00,
    "pending_credits": 0.00,
    "impacted_amount": -10.00,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 20.00,
        "available_balance": 0.00,
        "credit_balance": 0.00,
        "pending_credits": 0.00,
        "impacted_amount": -10.00
      }
    }
  },
  "gpa_order": {
    "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
    "amount": 10.00,
    "created_time": "2022-08-21T17:26:30Z",
    "last_modified_time": "2022-08-21T17:26:30Z",
    "transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
    "state": "PENDING",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 10.00,
      "source": {
        "type": "programgateway",
        "token": "**********dd5f",
        "active": true,
        "name": "PGFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2022-08-21T17:25:43Z",
        "last_modified_time": "2022-08-21T17:25:43Z"
      },
      "gateway_log": {
        "order_number": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
        "transaction_id": "your-jit-funding-token",
        "message": "Approved or completed successfully",
        "duration": 481,
        "timed_out": false,
        "response": {
          "code": "200",
          "data": {
          "jit_funding": {
            "token": "your-jit-funding-token",
            "method": "pgfs.authorization",
            "user_token": "your-jit-funding-user",
            "amount": 10.00,
            "original_jit_funding_token": "your-jit-funding-token",
            "address_verification": {
              "gateway": {
                  "on_file": {
                    "street_address": "2000 High St",
                    "postal_code": "94601"
                  },
                  "response": {
                    "code": "0000",
                    "memo": "Address and postal code match"
                  }
                }
              }
            }
          }
        }
      }
    },
    "funding_source_token": "**********dd5f",
    "jit_funding": {
      "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
      "method": "pgfs.authorization",
      "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
      "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
      "amount": 10.00
    },
    "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
    "currency_code": "USD"
  },
  "duration": 622,
  "created_time": "2022-08-21T17:26:29Z",
  "user_transaction_time": "2022-08-21T17:26:29Z",
  "issuer_received_time": "2022-08-21T17:26:29Z",
  "settlement_date": "2022-08-21T00:00:00Z",
  "issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
  "request_amount": 10.00,
  "amount": 10.00,
  "currency_conversion": {
  "network": {
      "original_amount": 10.00,
      "conversion_rate": 1.000000,
      "original_currency_code": "840",
      "dynamic_currency_conversion": "false"
    }
  },
  "issuer_interchange_amount": 0.00,
  "currency_code": "USD",
  "approval_code": "761515",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0.00,
  "acquirer": {
    "institution_country": "840",
    "institution_id_code": "428399181",
    "retrieval_reference_number": "528294182583",
    "system_trace_audit_number": "656761"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_security_code_verification": {
    "type": "CVV1",
    "response": {
      "code": "0000",
      "memo": "Card security code match"
    }
  },
  "fraud": {
    "network": {
      "transaction_risk_score": 97,
      "account_risk_score": 7
    },
    "issuer_processor":{
      "score": "64",
      "risk_level": "MEDIUM",
      "recommended_action": "APPROVE",
      "rule_violations":
        [
          "24hr.velocity.exceeded"
        ]
    }
  },
  "cardholder_authentication_data": {
   "electronic_commerce_indicator": "authentication_successful",
   "verification_result": "verified",
   "verification_value_created_by": "issuer_acs"
  },
  "card_acceptor": {
    "mid": "000000000011111",
    "mcc": "6411",
    "name": "Aegis Fleet Services",
    "street_address": "111 Main St",
    "city": "Berkeley",
    "country_code": "USA"
  },
  "pos": {
    "pan_entry_mode": "MAG_STRIPE",
    "pin_entry_mode": "TRUE",
    "terminal_id": "TR100000",
    "terminal_attendance": "ATTENDED",
    "card_holder_presence": false,
    "card_presence": false,
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  },
  "transaction_metadata": {
    "payment_channel": "OTHER"
  }
}

​
Ledger-impacting transaction events

The following table indicates how certain transaction event types impact the ledger. A negative impact on the ledger means the transaction event removed funds from the account, and a positive impact means the transaction event added funds. The Sent To detail indicates to which endpoint the JIT Funding message was sent. The Event Type detail indicates whether the transaction event was sent in a temporary transaction message or a final transaction message. For more on temporary and final transactions, see Transactions in the payments ecosystem and The transaction lifecycle in the About Transactions guide. For the descriptions of transaction events, see Transaction events in the Event Types API reference.
TypePGFS MethodEvent Details
account.funding.authorizationpgfs.authorizationSent to:
Your gateway endpoint, your webhook endpoint

Event type:
Temporary

Ledger impact:
Negative
account.funding.authorization.clearingpgfs.authorization.captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
account.funding.auth_plus_capturepgfs.auth_plus_captureSent to:
Your gateway endpoint, your webhook endpoint

Event type:
Final

Ledger impact:
Negative
account.funding.authorization.reversalpgfs.authorization.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
account.funding.auth_plus_capture.reversalpgfs.authorization.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
authorizationpgfs.authorizationSent to:
Your gateway endpoint

Event type:
Temporary

Ledger impact:
Negative
authorization.advicepgfs.authorization.reversalSent to:
Your webhook endpoint

Event type:
Temporary

Ledger impact:
Positive
authorization.atm.withdrawalpgfs.authorizationSent to:
Your gateway endpoint

Event type:
Temporary

Ledger impact:
Negative
authorization.cashbackpgfs.authorizationSent to:
Your gateway endpoint

Event type:
Temporary

Ledger impact:
Negative
authorization.clearingpgfs.authorization.capture

pgfs.force_capture		Sent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
authorization.clearing.atm.withdrawalpgfs.authorization.captureSent to:
Your gateway endpoint

Event type:
Final

Ledger impact:
Negative
authorization.clearing.chargebackpgfs.authorization.capture.chargebackSent to:
Your webhook endpoint

Event type:
Temporary

Ledger impact:
Positive, if credit_user is true

None, if credit_user is false
authorization.clearing.chargeback.completedpgfs.authorization.capture.chargebackSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
authorization.clearing.chargeback.provisional.creditpgfs.authorization.capture.chargebackSent to:
Your webhook endpoint

Event type:
Final, requires settlement

Ledger impact:
Positive
authorization.clearing.chargeback.provisional.debitpgfs.authorization.capture.chargeback.reversalSent to:
Your webhook endpoint

Event type:
Final, requires settlement

Ledger impact:
Negative
authorization.clearing.chargeback.reversalpgfs.authorization.capture.chargeback.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative, if credit_user is true

None, if credit_user is false
authorization.clearing.chargeback.writeoffpgfs.authorization.capture.chargebackSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
authorization.clearing.representmentpgfs.authorization.capture.chargeback.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative, if credit_user is true

None, if credit_user is false and representment amount equals original amount

Positive, if credit_user is false and representment amount is less than original amount
authorization.incrementalpgfs.authorization.incrementalSent to:
Your gateway endpoint

Event type:
Temporary, requires settlement

Ledger impact:
Negative
authorization.clearing.quasi.cashpgfs.authorization.captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
authorization.clearing.cashbackpgfs.authorization.captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
authorization.quasi.cashpgfs.authorizationSent to:
Your gateway endpoint

Event type:
Temporary

Ledger impact:
Negative
authorization.reversalpgfs.authorization.reversalSent to:
Your webhook endpoint

Event type:
Temporary

Ledger impact:
Positive
authorization.reversal.issuerexpirationpgfs.authorization.reversalSent to:
Your webhook endpoint

Event type:
Temporary

Ledger impact:
Positive
billpayment.capturepgfs.billpayment.captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
billpayment.reversalpgfs.billpayment.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
gpa.creditpgfs.adjustment.creditSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
gpa.debitpgfs.adjustment.debitSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
original.credit.authorizationpgfs.original.credit.authorizationSent to:
Your gateway endpoint

Event type:
Temporary

Ledger impact:
Positive
original.credit.authorization.reversalpgfs.original.credit.authorization.reversalSent to:
Your webhook endpoint

Event type:
Temporary

Ledger impact:
Negative
original.credit.authorization.clearingpgfs.original.credit.authorization.clearingSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
original.credit.auth_plus_capturepgfs.original.credit.auth_plus_captureSent to:
Your gateway endpoint

Event type:
Final

Ledger impact:
Positive
original.credit.auth_plus_capture.reversalpgfs.original.credit.auth_plus_captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
pindebitpgfs.auth_plus_captureSent to:
Your gateway endpoint

Event type:
Final

Ledger impact:
Negative
pindebit.atm.withdrawalpgfs.auth_plus_captureSent to:
Your gateway endpoint

Event type:
Final

Ledger impact:
Negative
pindebit.authorizationpgfs.authorizationSent to:
Your gateway endpoint

Event type:
Temporary

Ledger impact:
Negative
pindebit.authorization.clearingpgfs.authorization.captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
pindebit.authorization.reversal.issuerexpirationpgfs.authorization.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
pindebit.cashbackpgfs.auth_plus_captureSent to:
Your gateway endpoint

Event type:
Final

Ledger impact:
Negative
pindebit.chargebackpgfs.pindebit.chargebackSent to:
Your webhook endpoint

Event type:
Temporary

Ledger impact:
Positive, if credit_user is true

None, if credit_user is false
pindebit.chargeback.completednoneSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
pindebit.chargeback.reversalpgfs.pindebit.chargeback.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative, if credit_user is true

None, if credit_user is false
pindebit.chargeback.writeoffnoneSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
pindebit.credit.adjustmentpgfs.authorization.captureSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
pindebit.quasi.cashpgfs.auth_plus_captureSent to:
Your gateway endpoint

Event type:
Final

Ledger impact:
Negative
pindebit.refundpgfs.refundSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
pindebit.refund.reversalpgfs.refund.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Negative
pindebit.reversalpgfs.auth_plus_capture.reversalSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
refundpgfs.refundSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive
refund.authorization.clearingpgfs.refundSent to:
Your webhook endpoint

Event type:
Final

Ledger impact:
Positive

​
Example chargeback scenario

The following code blocks show sample webhook notifications as they would appear in a scenario where a chargeback with provisional credit was initiated and the case was lost. For more on chargebacks and chargeback transitions, see the About Disputes guide and Chargeback transition events in the Event Types API reference.

​
Chargeback authorization

The following code block shows a sample webhook notification for a chargeback authorization of 12.50 USD, for which the cardholder is given a provisional credit:
JSON
{
  "transactions": [
    {
      "type": "authorization.clearing.chargeback",
      "state": "COMPLETION",
      "token": "1927",
      "user_token": "r_user_2",
      "acting_user_token": "r_user_2",
      "card_token": "r_card_2",
      "preceding_related_transaction_token": "1925",
      "gpa": {
        "currency_code": "USD",
        "ledger_balance": 1028.71,
        "available_balance": 0.00,
        "credit_balance": 0.00,
        "pending_credits": 10.00,
        "impacted_amount": 12.50,
        "balances": {
          "USD": {
            "currency_code": "USD",
            "ledger_balance": 1028.71,
            "available_balance": 0.00,
            "credit_balance": 0.00,
            "pending_credits": 10.00,
            "impacted_amount": 12.50
          }
        }
      },
      "duration": 658,
      "created_time": "2023-02-05T18:02:43Z",
      "user_transaction_time": "2023-02-05T18:02:43Z",
      "request_amount": 12.50,
      "amount": 12.50,
      "currency_code": "USD",
      "approval_code": "302059",
      "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
      },
      "gpa_order_unload": {
        "token": "f7bd4b8e-66aa-4d71-9301-1ac0610d33f1",
        "amount": 12.50,
        "created_time": "2023-02-05T18:02:43Z",
        "last_modified_time": "2023-02-05T18:02:43Z",
        "transaction_token": "1928",
        "state": "COMPLETION",
        "response": {
          "code": "0000",
          "memo": "Approved or completed successfully"
        },
      "funding": {
        "amount": 12.50,
        "source": {
          "type": "programgateway",
          "token": "**********fs_1",
          "active": true,
          "name": "RitzPGFS",
          "is_default_account": false,
          "created_time": "2022-05-09T18:16:07Z",
          "last_modified_time": "2022-05-09T18:16:07Z"
        }
      },
      "funding_source_token": "**********fs_1",
        "jit_funding": {
          "token": "a4e2b778-9d04-4b97-8a02-207555f833be",
          "method": "pgfs.authorization.capture.chargeback",
          "user_token": "r_user_2",
          "acting_user_token": "r_user_2",
          "amount": 12.50
        }
      },
      "chargeback": {
        "token": "2c4c2130-1f0d-41b3-8ab6-0c1b1857f70e",
        "transaction_token": "1925",
        "amount": 12.50,
        "reason_code": "30",
        "memo": "Chargeback Webhook Testing",
        "state": "INITIATED",
        "channel": "ISSUER",
        "network": "VISA",
        "credit_user": true
      },
      "network": "VISA",
      "subnetwork": "VISANET",
      "acquirer_fee_amount": 0.00,
      "acquirer": {
        "institution_id_code": "000000",
        "system_trace_audit_number": "000037"
      },
      "user": {
        "metadata": {
          "car": "Benz",
          "company": "Marqeta",
          "fav_sports": "cricket",
          "home_town": "India",
          "key1": "value1",
          "key2": "value2"
        }
      },
      "card": {
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "card_acceptor": {
        "mid": "998877665544",
        "mcc": "6411",
        "name": "Sample Merchant",
        "street_address": "123 Elm",
        "city": "Jamestown",
        "state": "CA",
        "postal_code": "94608",
        "country_code": "USA"
      },
      "pos": {
        "partial_approval_capable": false,
        "purchase_amount_only": false,
        "is_recurring": false
      }
    }
  ]
}
  • The type value of authorization.clearing.chargeback shows that a chargeback was initiated.
  • The token value shows that the unique identifier of the chargeback is 1927.
  • The preceding_related_transaction_token shows that the unique identifier of the disputed transaction is 1925.
  • The amount value shows that the chargeback amount is 12.50.
  • The currency_code value shows that the chargeback amount is in USD.
  • The gpa.impacted_amount value shows that the chargeback has a positive impact on the ledger by 12.50.
  • The gpa.currency_code value shows that the ledger impact amount is in USD.
  • The credit_user field set to true shows that the cardholder was given a provisional credit.
In this case, you can update your account ledger by adding 12.50 USD to the account balance.

​
Chargeback transition

Sent with the chargeback authorization, the following code block shows a sample webhook notification sent because the chargeback was initiated:
JSON
{
  "chargebacktransitions": [
    {
      "token": "82b2aadb-02b6-41ac-962c-f8668b86b685",
      "state": "INITIATED",
      "channel": "ISSUER",
      "chargeback_token": "2c4c2130-1f0d-41b3-8ab6-0c1b1857f70e",
      "transaction_token": "1927",
      "created_time": "2023-02-05T18:02:43Z",
      "last_modified_time": "2023-02-05T18:02:43Z",
      "type": "initiated"
    }
  ]
}
  • The state value shows that the chargeback is currently in an initiated state.
  • The transaction_token value shows that the unique identifier of the transaction responsible for the chargeback transition is 1927, the chargeback authorization.
  • The type value of initiated shows that the chargeback has been created.

​
Chargeback reversal

The following code block shows a sample webhook notification for a chargeback reversal of 12.50 USD, sent because the cardholder lost the chargeback case, which reversed the provisional credit given when the chargeback was initiated:
JSON
{
  "transactions": [
    {
      "type": "authorization.clearing.chargeback.reversal",
      "state": "CLEARED",
      "token": "1929",
      "user_token": "r_user_2",
      "acting_user_token": "r_user_2",
      "card_token": "r_card_2",
      "preceding_related_transaction_token": "1927",
      "gpa": {
        "currency_code": "USD",
        "ledger_balance": 1028.71,
        "available_balance": 0.00,
        "credit_balance": 0.00,
        "pending_credits": 10.00,
        "impacted_amount": -12.50,
        "balances": {
          "USD": {
            "currency_code": "USD",
            "ledger_balance": 1028.71,
            "available_balance": 0.00,
            "credit_balance": 0.00,
            "pending_credits": 10.00,
            "impacted_amount": -12.50
          }
        }
      },
      "gpa_order": {
        "token": "5523d867-cd30-4cec-bacd-9f6d0d450476",
        "amount": 12.50,
        "created_time": "2023-02-05T18:06:26Z",
        "last_modified_time": "2023-02-05T18:06:26Z",
        "transaction_token": "1930",
        "state": "COMPLETION",
        "response": {
          "code": "0000",
          "memo": "Approved or completed successfully"
        },
        "funding": {
          "amount": 12.50,
          "source": {
            "type": "programgateway",
            "token": "**********fs_1",
            "active": true,
            "name": "RitzPGFS",
            "is_default_account": false,
            "created_time": "2022-05-09T18:16:07Z",
            "last_modified_time": "2022-05-09T18:16:07Z"
          }
        },
        "funding_source_token": "**********fs_1",
        "jit_funding": {
          "token": "de030fde-d21c-4930-8f53-30aa72e8a00c",
          "method": "pgfs.authorization.capture.chargeback.reversal",
          "user_token": "r_user_2",
          "acting_user_token": "r_user_2",
          "amount": 12.50
        },
        "user_token": "r_user_2",
        "currency_code": "USD"
      },
      "duration": 166,
      "created_time": "2023-02-05T18:06:26Z",
      "user_transaction_time": "2023-02-05T18:06:26Z",
      "request_amount": 12.50,
      "amount": 12.50,
      "currency_code": "USD",
      "approval_code": "302059",
      "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
      },
      "chargeback": {
        "token": "2c4c2130-1f0d-41b3-8ab6-0c1b1857f70e",
        "transaction_token": "1925",
        "amount": 12.50,
        "reason_code": "30",
        "memo": "Chargeback Webhook Testing",
        "state": "CASE_LOST",
        "channel": "ISSUER",
        "network": "VISA",
        "credit_user": true,
        "created_time": "2023-02-05T18:02:43Z",
        "last_modified_time": "2023-02-05T18:02:43Z"
      },
      "network": "VISA",
      "subnetwork": "VISANET",
      "acquirer_fee_amount": 0.00,
      "acquirer": {
        "institution_id_code": "000000",
        "system_trace_audit_number": "000038"
      },
      "user": {
        "metadata": {
          "car": "Benz",
          "company": "Marqeta",
          "fav_sports": "cricket",
          "home_town": "India",
          "key1": "value1",
          "key2": "value2"
        }
      },
      "card": {
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "card_acceptor": {
        "mid": "998877665544",
        "mcc": "6411",
        "name": "Sample Merchant",
        "street_address": "123 Elm",
        "city": "Jamestown",
        "state": "CA",
        "postal_code": "94608",
        "country_code": "USA"
      },
      "pos": {
        "partial_approval_capable": false,
        "purchase_amount_only": false,
        "is_recurring": false
      }
    }
  ]
}
  • The type value of authorization.clearing.chargeback.reversal shows that the chargeback authorization was reversed.
  • The token value shows that the unique identifier of the chargeback reversal is 1929.
  • The preceding_related_transaction_token shows that the unique identifier of the chargeback authorization, the related transaction preceding the chargeback reversal, is 1927.
  • The gpa.impacted_amount value shows that the chargeback reversal has a negative impact on the ledger by 12.50.
  • The gpa.currency_code value shows that the impacted amount is in USD.
  • The gpa_order.jit_funding.method value of pgfs.authorization.capture.chargeback.reversal shows that the chargeback authorization was reversed, debiting funds from the funding source.
  • The chargeback.transaction_token shows that the unique identifier of the chargeback authorization is 1925.
In this case, you can update your account ledger by removing 12.50 USD from the account balance.

​
Chargeback transition

Sent with the chargeback reversal, the following code block shows a sample webhook notification sent because the chargeback transitioned to a case lost state:
JSON
{
  "chargebacktransitions": [
    {
      "token": "3bfaad32-fe59-4309-bd0a-14d17957ff64",
      "state": "CASE_LOST",
      "previous_state": "INITIATED",
      "channel": "ISSUER",
      "chargeback_token": "2c4c2130-1f0d-41b3-8ab6-0c1b1857f70e",
      "reason": "Testing Transitions",
      "transaction_token": "1929",
      "created_time": "2023-02-05T18:06:26Z",
      "last_modified_time": "2023-02-05T18:06:26Z",
      "type": "case.lost"
    }
  ]
}
  • The state value shows that the chargeback is currently in a case lost state.
  • The previous_state value shows that the chargeback transitioned to its current state from an initiated state.
  • The transaction_token value shows that the unique identifier of the transaction responsible for the chargeback transition is 1929, the chargeback reversal.
  • The type value of case.lost shows that the chargeback case was lost.

​
Balances in Gateway JIT Funding responses

In response to a balance inquiry or withdrawal made at an ATM, your gateway sends a JIT Funding response to the Marqeta platform containing the balances object, which contains information about the account’s balances by currency. To ensure your JIT Funding responses are accurate and up-to-date, keep your account ledgers current. To ensure your JIT Funding response body adheres to the Marqeta platform’s specifications, see JIT Funding responses in the Gateway JIT Funding Messages API reference.

​
The balances object

Populate the balances object, embedded in the jit_funding object, with the following information from your account ledgers:
  • Currency code – Set the currency_code value to the three-digit ISO 4217 currency type of the balance, such as USD.
  • Ledger balance – Set the ledger_balance value to the funds available to spend immediately from the account, including any funds from authorized transactions that have not yet cleared.
  • Available balance – Set the available_balance value to the amount of the ledger balance minus any authorized transactions that have not yet cleared on the account. The ATM displays this amount as the balance.
  • Pending credits – Set the pending_credits value to the amount of the ACH loads that have been accepted, but for which the funding time has not yet elapsed.
The following code block shows a sample balances object with a ledger balance and available balance of 100.00 USD as it would appear in a JIT Funding response to a balance inquiry made at an ATM:
JSON
{
  "jit_funding": {
    "token": "b0a889ec-d7e2-4744-bc09-aa86b0738500",
    "method": "pgfs.balanceinquiry",
    "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
    "amount": 0.00,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100.00,
        "available_balance": 100.00,
        "pending_credits": 0.00
      }
    }
  }
}

​
Best practices for ledger maintenance

The following best practices can help keep your ledger current:
  • Subscribe to all transaction event types when configuring your webhook endpoint and use the created_time field to determine what order the transactions were created. For details, see the About Webhooks guide.
  • Follow Generally Accepted Accounting Principles (GAAP) to know when, where, and why money moves out of accounts.
  • Reconcile all transactions, especially force-post or offline transactions.
  • Keep a backup of the ledger in the cloud or keep a hard copy on a paper spreadsheet.

Related topics

Expense Management with Gateway JIT FundingConfiguring Managed JIT FundingAbout Just-in-Time FundingJust-in-Time Funding OverviewJust-in-Time Funding in Europe