/

10 minute read

June 17, 2020

Ledger Management with JIT Funding

An account ledger is the system of record that keeps track of all transactions that occur on a user or business account. It’s 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.

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.

At the end of this guide, you should understand:

  • 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 USD as it would appear in a JIT Funding request or notification:

 "gpa": {
     "currency_code": "USD",
     "currency_code": "USD",
     "ledger_balance": 20,
     "available_balance": 0,
     "credit_balance": 0,
     "pending_credits": 0,
     "impacted_amount": -10,
     "balances": {
         "USD": {
             "currency_code": "USD",
             "ledger_balance": 20,
             "available_balance": 0,
             "credit_balance": 0,
             "pending_credits": 0,
             "impacted_amount": -10
         }
     }
 },

Is this helpful?

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 that impacts the ledger by -10 USD:

{
     "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,
         "available_balance": 0,
         "credit_balance": 0,
         "pending_credits": 0,
         "impacted_amount": -10,
         "balances": {
             "USD": {
                 "currency_code": "USD",
                 "ledger_balance": 20,
                 "available_balance": 0,
                 "credit_balance": 0,
                 "pending_credits": 0,
                 "impacted_amount": -10
             }
         }
     },
     "gpa_order": {
         "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
         "amount": 10,
         "created_time": "2018-08-21T17:26:30Z",
         "last_modified_time": "2018-08-21T17:26:30Z",
         "transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
         "state": "PENDING",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 10,
             "source": {
                 "type": "programgateway",
                 "token": "**********dd5f",
                 "active": true,
                 "name": "PGFS for simulating transactions",
                 "is_default_account": false,
                 "created_time": "2018-08-21T17:25:43Z",
                 "last_modified_time": "2018-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,
                             "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
         },
         "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
         "currency_code": "USD"
     },
     "duration": 622,
     "created_time": "2018-08-21T17:26:29Z",
     "user_transaction_time": "2018-08-21T17:26:29Z",
     "issuer_received_time": "2018-08-21T17:26:29Z",
     "settlement_date": "2018-08-21T00:00:00Z",
     "issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
     "request_amount": 10,
     "amount": 10,
     "currency_conversion": {
   	 "network": {
      	     "original_amount": 10,
      	     "conversion_rate": 1.000000,
      	     "original_currency_code": "840"
         }
     },
     "issuer_interchange_amount": 0,
     "currency_code": "USD",
     "approval_code": "761515",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "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": "Chicken Tooth Music",
         "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"
     }
 }

Is this helpful?

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 column indicates to which endpoint the JIT Funding message was sent. The Final vs. Temporary column indicates whether the transaction event was sent in a temporary or 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.

Type PGFS Method Sent To Temporary vs. Final Ledger Impact

authorization

pgfs.authorization

Your gateway endpoint

Temporary

Negative

authorization.advice

pgfs.authorization

Your webhook endpoint

Temporary

Positive

authorization.clearing

pgfs.authorization.
capture

pgfs.force_capture

Your webhook endpoint

Final

Negative

authorization.clearing.
chargeback

pgfs.authorization.
capture.chargeback

Your webhook endpoint

Temporary

Positive if credit_user is true

None if credit_user is false

authorization.clearing.
chargeback.completed

pgfs.authorization.
capture.chargeback

Your webhook endpoint

Final

Positive

authorization.clearing.
chargeback.provisional.
credit

pgfs.authorization.
capture.chargeback

Your webhook endpoint

Final, requires settlement

Positive

authorization.clearing.
chargeback.provisional.
debit

pgfs.authorization.
capture.chargeback.
reversal

Your webhook endpoint

Final, requires settlement

Negative

authorization.clearing.
chargeback.reversal

pgfs.authorization.
capture.chargeback.
reversal

Your webhook endpoint

Final

Negative if credit_user is true

None if credit_user is false

authorization.clearing.
chargeback.writeoff

pgfs.authorization.
capture.chargeback

Your webhook endpoint

Final

Positive

authorization.clearing.
representment

pgfs.authorization.
capture.chargeback.
reversal

Your webhook endpoint

Final

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

pgfs.authorization.
incremental

Your gateway endpoint

Temporary, requires settlement

Negative

authorization.reversal

pgfs.authorization.
reversal

Your webhook endpoint

Temporary

Positive

authorization.reversal.
issuerexpiration

pgfs.authorization.
reversal

Your webhook endpoint

Temporary

Positive

dispute.credit

none

Your webhook endpoint

Final

Positive

dispute.debit

none

Your webhook endpoint

Final

Negative

gpa.credit

pgfs.adjustment.
credit

Your webhook endpoint

Final

Positive

gpa.debit

pgfs.adjustment.
debit

Your webhook endpoint

Final

Negative

original.credit.
authorization

pgfs.original.credit.
authorization

Your gateway endpoint

Temporary

Positive

original.credit.
authorization.reversal

pgfs.original.credit.
authorization.
reversal

Your webhook endpoint

Temporary

Negative

original.credit.
authorization.clearing

pgfs.original.credit.
authorization.
clearing

Your webhook endpoint

Final

Positive

original.credit.
auth_plus_capture

pgfs.original.credit.
auth_plus_capture

Your gateway endpoint

Final

Positive

original.credit.
auth_plus_capture.
reversal

pgfs.original.credit.
auth_plus_capture

Your webhook endpoint

Final

Negative

pindebit

pgfs.
auth_plus_capture

Your gateway endpoint

Final

Negative

pindebit.atm.
withdrawal

pgfs.
auth_plus_capture

Your gateway endpoint

Final

Negative

pindebit.authorization

pgfs.authorization

Your gateway endpoint

Temporary

None

pindebit.authorization.
clearing

pgfs.authorization.
capture

Your webhook endpoint

Final

Negative

pindebit.authorization.
reversal.
issuerexpiration

pgfs.authorization.
reversal

Your webhook endpoint

Final

Positive

pindebit.cashback

pgfs.
auth_plus_capture

Your gateway endpoint

Final

Negative

pindebit.chargeback

pgfs.pindebit.
chargeback

Your gateway endpoint

Temporary

Positive if credit_user is true

None if credit_user is false

pindebit.chargeback.
completed

none

Your webhook endpoint

Final

Positive

pindebit.chargeback.
reversal

pgfs.pindebit.
chargeback.
reversal

Your webhook endpoint

Final

Negative if credit_user is true

None if credit_user is false

pindebit.chargeback.
writeoff

none

Your webhook endpoint

Final

Positive

pindebit.refund

pgfs.refund

Your webhook endpoint

Final

Positive

pindebit.refund.
reversal

pgfs.refund.reversal

Your webhook endpoint

Final

Negative

pindebit.reversal

pgfs.
auth_plus_capture. reversal

Your webhook endpoint

Final

Positive

refund

pgfs.refund

Your webhook endpoint

Final

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 Managing Chargebacks 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.5 USD, for which the cardholder is given a provisional credit:

{
  "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,
         "credit_balance": 0,
         "pending_credits": 10,
         "impacted_amount": 12.5,
         "balances": {
             "USD": {
		     "currency_code": "USD",
                 "ledger_balance": 1028.71,
                 "available_balance": 0,
                 "credit_balance": 0,
                 "pending_credits": 10,
                 "impacted_amount": 12.5,
             }
         }
     },
     "duration": 658,
     "created_time": "2019-02-05T18:02:43Z",
     "user_transaction_time": "2019-02-05T18:02:43Z",
     "request_amount": 12.5,
     "amount": 12.5,
     "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.5,
         "created_time": "2019-02-05T18:02:43Z",
         "last_modified_time": "2019-02-05T18:02:43Z",
         "transaction_token": "1928",
         "state": "COMPLETION",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 12.5,
             "source": {
                 "type": "programgateway",
                 "token": "**********fs_1",
                 "active": true,
                 "name": "RitzPGFS",
                 "is_default_account": false,
                 "created_time": "2018-05-09T18:16:07Z",
                 "last_modified_time": "2018-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.5
         }
     },
     "chargeback": {
         "token": "2c4c2130-1f0d-41b3-8ab6-0c1b1857f70e",
         "transaction_token": "1925",
         "amount": 12.5,
         "reason_description": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
         "reason_code": "30",
         "memo": "Chargeback Webhook Testing",
         "state": "INITIATED",
         "channel": "ISSUER",
         "network": "VISA",
         "credit_user": true
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "acquirer": {
         "institution_id_code": "000000",
         "system_trace_audit_number": "000037"
     },
     "user": {
         "metadata": {
             "car":
             "Benz",
             "company": "Marqeta",
             "fav_sprots": "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
     }
    }
  ]
}

Is this helpful?

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

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

  • 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.5 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:

{
  "chargebacktransitions": [
    {
      "token": "82b2aadb-02b6-41ac-962c-f8668b86b685",
      "state": "INITIATED",
      "channel": "ISSUER",
      "chargeback_token": "2c4c2130-1f0d-41b3-8ab6-0c1b1857f70e",
      "transaction_token": "1927",
      "created_time": "2019-02-05T18:02:43Z",
      "last_modified_time": "2019-02-05T18:02:43Z",
      "type": "initiated"
    }
  ]
}

Is this helpful?

  • 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.5 USD, sent because the cardholder lost the chargeback case, which reversed the provisional credit given when the chargeback was initiated:

{
  "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,
         "credit_balance": 0,
         "pending_credits": 10,
         "impacted_amount": -12.5,
         "balances": {
             "USD": {
                 "currency_code":
                 "USD",
                 "ledger_balance": 1028.71,
                 "available_balance": 0,
                 "credit_balance": 0,
                 "pending_credits": 10,
                 "impacted_amount": -12.5
             }
         }
     },
     "gpa_order": {
         "token": "5523d867-cd30-4cec-bacd-9f6d0d450476",
         "amount": 12.5,
         "created_time": "2019-02-05T18:06:26Z",
         "last_modified_time": "2019-02-05T18:06:26Z",
         "transaction_token": "1930",
         "state": "COMPLETION",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 12.5,
             "source": {
                 "type": "programgateway",
                 "token": "**********fs_1",
                 "active": true,
                 "name": "RitzPGFS",
                 "is_default_account": false,
                 "created_time": "2018-05-09T18:16:07Z",
                 "last_modified_time": "2018-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.5
         },
        "user_token": "r_user_2",
        "currency_code": "USD"
     },
     "duration": 166,
     "created_time": "2019-02-05T18:06:26Z",
     "user_transaction_time": "2019-02-05T18:06:26Z",
     "request_amount": 12.5,
     "amount": 12.5,
     "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.5,
         "reason_description": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
         "reason_code": "30",
         "memo": "Chargeback Webhook Testing",
         "state": "CASE_LOST",
         "channel": "ISSUER",
         "network": "VISA",
         "credit_user": true,
         "created_time": "2019-02-05T18:02:43Z",
         "last_modified_time": "2019-02-05T18:02:43Z"
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "acquirer": {
         "institution_id_code": "000000",
         "system_trace_audit_number": "000038"
     },
     "user": {
         "metadata": {
             "car": "Benz",
             "company": "Marqeta",
             "fav_sprots": "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
     }
    }
  ]
}

Is this helpful?

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

  • 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.5 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:

{
  "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": "2019-02-05T18:06:26Z",
      "last_modified_time": "2019-02-05T18:06:26Z",
      "type": "case.lost"
    }
  ]
}

Is this helpful?

  • 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-character 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 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 USD as it would appear in a JIT Funding response to a balance inquiry made at an ATM:

{
  "jit_funding": {
    "token": "b0a889ec-d7e2-4744-bc09-aa86b0738500",
    "method": "pgfs.balanceinquiry",
    "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
    "balances" : {
      "USD" : {
        "currency_code" : "USD",
        "ledger_balance" : 100.00,
        "available_balance" : 100.00,
        "pending_credits" : 0.00
      }
    }
  }
}

Is this helpful?

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.

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.