DOCS

New!

/

5 minute read

May 3, 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 more, see the Balances API reference.

At the end of this guide, you should understand:

  • How to use information in JIT Funding messages to help manage your ledger.

  • Which transaction events impact the ledger.

  • Best practices for ledger maintenance.

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 Managed JIT, use the data sent to your webhook endpoint. For Gateway JIT, note that the JIT Funding message type, actionable or informative, does not indicate whether the transaction impacts the ledger, as both can. For more, see the Gateway JIT Funding Messages API reference. For more on Managed vs. Gateway JIT, see the About Just In Time (JIT) Funding guide.

Transaction 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 message:

    "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 transaction type.

The following code block shows a sample JIT Funding message 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 is a final or temporary transaction. For more, see the About Transactions guide.

For the descriptions of transaction events, see the Event Types API reference.

Type PGFS Method Sent To Ledger Impact

authorization

pgfs.authorization

Your gateway endpoint

Negative

authorization.advice

pgfs.authorization

Your gateway endpoint

Positive

authorization.clearing

pgfs.authorization.capture

pgfs.force_capture

Your webhook endpoint

Negative

authorization.clearing.chargeback

pgfs.authorization.capture.chargeback

Your webhook endpoint

Positive if credit_user is true

None if credit_user is false

authorization.clearing.chargeback.completed

pgfs.authorization.capture.chargeback

Your webhook endpoint

Positive

authorization.clearing.chargeback.provisional.credit

pgfs.authorization.capture.chargeback

Your webhook endpoint

Positive

authorization.clearing.chargeback.provisional.debit

pgfs.authorization.capture.chargeback.reversal

Your webhook endpoint

Negative

authorization.clearing.chargeback.reversal

pgfs.authorization.capture.chargeback.reversal

Your webhook endpoint

Negative if credit_user is true

None if credit_user is false

authorization.clearing.chargeback.writeoff

pgfs.authorization.capture.chargeback

Your webhook endpoint

Positive

authorization.clearing.representment

pgfs.authorization.capture.chargeback.reversal

Your webhook endpoint

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

Negative

authorization.reversal

pgfs.authorization.reversal

Your webhook endpoint

Positive

authorization.reversal.issuerexpiration

pgfs.authorization.reversal

Your webhook endpoint

Positive

dispute.credit

none

Your webhook endpoint

Positive

dispute.debit

none

Your webhook endpoint

Negative

gpa.credit

pgfs.adjustment.credit

Your webhook endpoint

Positive

gpa.debit

pgfs.adjustment.debit

Your webhook endpoint

Negative

original.credit.authorization

pgfs.original.credit.authorization

Your gateway endpoint

Positive

original.credit.authorization.reversal

pgfs.original.credit.authorization.reversal

Your webhook endpoint

Negative

original.credit.authorization.clearing

pgfs.original.credit.authorization.clearing

Your webhook endpoint

Positive

original.credit.auth_plus_capture

pgfs.original.credit.auth_plus_capture

Your gateway endpoint

Positive

original.credit.auth_plus_capture.reversal

pgfs.original.credit.auth_plus_capture

Your webhook endpoint

Negative

pindebit

pgfs.auth_plus_capture

Your gateway endpoint

Negative

pindebit.atm.withdrawal

pgfs.auth_plus_capture

Your gateway endpoint

Negative

pindebit.authorization

pgfs.authorization

Your gateway endpoint

None

pindebit.authorization.clearing

pgfs.authorization.capture

Your webhook endpoint

Negative

pindebit.authorization.reversal.issuerexpiration

pgfs.authorization.reversal

Your webhook endpoint

Positive

pindebit.cashback

pgfs.auth_plus_capture

Your gateway endpoint

Negative

pindebit.chargeback

pgfs.pindebit.chargeback

Your gateway endpoint

Positive if credit_user is true

None if credit_user is false

pindebit.chargeback.completed

none

Your webhook endpoint

Positive

pindebit.chargeback.reversal

pgfs.pindebit.chargeback.reversal

Your webhook endpoint

Negative if credit_user is true

None if credit_user is false

pindebit.chargeback.writeoff

none

Your webhook endpoint

Positive

pindebit.refund

pgfs.refund

Your webhook endpoint

Positive

pindebit.refund.reversal

pgfs.refund.reversal

Your webhook endpoint

Negative

pindebit.reversal

pgfs.auth_plus_capture.reversal

Your webhook endpoint

Positive

refund

pgfs.refund

Your webhook endpoint

Positive

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 the order transactions were created. For more, 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.