Managing Timeouts

Accounting errors can arise if the Just-in-Time (JIT) Funding gateway on your system times out. This page describes how to manage such occurrences.

Note
This page applies only to Gateway JIT Funding and does not apply to Managed JIT Funding. For more information on JIT Funding, see About Just-in-Time Funding.

Identifying and resolving timeouts

When a transaction requires Gateway JIT Funding (other than due to a force capture), the Marqeta platform delays the response to the card network and sends a request to your JIT Funding gateway. Because the card network requires a timely response from the Marqeta platform, there is a timeout limit on the response from your gateway. If your gateway doesn’t respond to the JIT Funding request within three seconds, the Marqeta platform declines the transaction to the card network. Whenever a timeout occurs, the potential arises for an accounting error in your system. For example, consider the following scenario:

The Marqeta platform calls your gateway for a $100 authorization.

After three seconds without receiving a response, the Marqeta platform times out the request.

The Marqeta platform declines the transaction to the card network.

A few seconds later, your system finishes processing the authorization and attempts to respond with an authorization for $100.

Unless your system identifies the timeout and reverses the authorization for $100, it may become out of sync with the actual state of the transaction and account balance.

The Marqeta platform webhooks provide a solution for identifying these timeouts so you can resolve out-of-sync issues in whatever way your business model requires. Webhooks are push-style event notifications that the Marqeta platform sends to an endpoint on your system (not the same as the JIT Funding gateway endpoint). The Marqeta platform sends notifications asynchronously less than a second after each transaction completes and provide information to identify JIT Funding requests that timed out. The following sample notification shows that a GPA funding order was declined as a result of a timed-out JIT Funding request. Take note of the gateway_log.timed_out field. A value of true indicates that the associated JIT Funding request timed out. Other important information contained in these webhook notifications includes:

Transaction token
Transaction type
Transaction state
Amounts and funding source
Token of the preceding related transaction

JSON

{
  "token": "6ba2c8d9-a678-4469-8b8b-0dc49948741d",
  "type": "gpa.credit.authorization",
  "state": "ERROR",
  "duration": 3090,
  "amount": 10.22,
  "response": {
    "code": "1842",
    "memo": "Account load failed"
  },
  "network": "MARQETA",
  "user_token": "cbd5375a-ce6d-436b-83a7-11b86327b932",
  "acting_user_token": "cbd5375a-ce6d-436b-83a7-11b86327b932",
  "card_token": "50b178a6-6b6f-4d03-be8f-2664ca472a0b",
  "created_time": "2022-10-07T01:25:29Z",
  "user_transaction_time": "2022-10-07T01:25:29Z",
  "preceding_related_transaction_token": "c9a6c511-40c5-4d62-adc2-40eada9e3613",
  "gpa": {
    "ledger_balance": 0.00,
    "available_balance": 0.00,
    "credit_balance": 0.00,
    "pending_credits": 0.00
  },
  "gpa_order": {
    "token": "de8d8245-2b77-4725-9eb5-c2024bb0b8dd",
    "amount": 10.22,
    "funding": {
      "amount": 10.22,
      "source": {
        "type": "programgateway",
        "token": "**********57ec",
        "active": true,
        "name": "Marqeta QA PGFS 1",
        "is_default_account": false,
        "created_time": "2022-10-07T00:48:02Z",
        "last_modified_time": "2022-10-07T00:48:02Z"
      },
      "gateway_log": {
        "message": "Operation timeout",
        "duration": 3002,
        "order_number": "c9a6c511-40c5-4d62-adc2-40eada9e3613",
        "timed_out": true,    // Indicates JIT Funding request timed out.
        "response": {
          "code": "97"
        }
      }
    },
    "state": "ERROR",
    "tags": "TIMEOUT",
    "transaction_token": "6ba2c8d9-a678-4469-8b8b-0dc49948741d",
    "jit_funding": {
      "token": "785c1afb-e742-4d2e-84d7-d381d480c0ae",
      "method": "pgfs.authorization",
      "amount": 10.22,
      "user_token": "cbd5375a-ce6d-436b-83a7-11b86327b932"
    },
    "response": {
      "code": "1842",
      "memo": "Account load failed"
    },
    "created_time": "2022-10-07T01:25:29Z",
    "last_modified_time": "2022-10-07T01:25:29Z",
    "user_token": "cbd5375a-ce6d-436b-83a7-11b86327b932",
    "currency_code": "USD",
    "funding_source_token": "**********57ec"
  },
  "subnetwork": "GATEWAY_JIT"
}

For more information, see Gateway JIT Funding Messages.

​Identifying and resolving timeouts

Identifying and resolving timeouts