DOCS

New!

/

25 minute read

August 3, 2019

Gateway JIT Funding Messages

To participate in Gateway JIT Funding decisions, your system must handle messages sent by the Marqeta platform and return the appropriate response.

The Marqeta platform and your system exchange messages of the following types:

  • JIT Funding requests are actionable messages sent by the Marqeta platform to an endpoint on your system referred to as the JIT Funding gateway. These synchronous messages request permission to fund a specific transaction or to answer a balance inquiry.

  • JIT Funding responses are sent by your JIT Funding gateway to the Marqeta platform in response to a funding request or balance inquiry. Your gateway endpoint must respond to each funding request by approving or denying funding for the associated transaction. Your gateway must respond to each balance inquiry with the currently available balance for the account associated with the specified card. In addition, you can inject custom metadata into each response. Messages sent to the Marqeta platform must use the HTTPS protocol.

  • JIT Funding notifications are informative messages sent by the Marqeta platform to your webhook endpoint (not the JIT Funding gateway endpoint). These asynchronous messages contain the entire transaction and inform you about its ultimate outcome. Use JIT Funding notifications to validate that the Marqeta platform receives and correctly processes each of your funding responses.

Note
These messages apply only to Gateway JIT Funding setups. For more information about JIT Funding, see About Just-in-Time Funding.

The jit_funding object

Each JIT Funding message sent to your system contains a jit_funding object embedded in a gpa_order or gpa_order_unload object. Messages containing the gpa_order object indicate a load event, where funds are loaded into an account, while those containing the gpa_order_unload object indicate an unload event, where funds are removed from an account.

Note
JIT Funding requests for non-financial balance inquiries (where the method is pgfs.balanceinquiry) have no associated transaction or movement of funds and do not contain a gpa_order, gpa_order_unload, or jit_funding object.

The jit_funding object contains information about the funding event, including the associated user token and transaction amount. The method field indicates the type of transaction and whether the message is an actionable funding request sent to your gateway endpoint or an informative message sent to your webhook endpoint.

Your gateway’s JIT Funding response must include the jit_funding object with the method found in the matching request.

The following table summarizes the available methods:

Method Purpose Funding Event Description

pgfs.adjustment.credit

Informative

Load

The Marqeta platform made a balance adjustment by crediting the gateway program funding source.

pgfs.adjustment.debit

Informative

Unload

The Marqeta platform made a balance adjustment by debiting the GPA.

pgfs.auth_plus_capture

Actionable

Load

Request for authorization to fund a user’s GPA and capture those funds. Used when the Marqeta platform receives a single-message financial transaction, such as a PIN debit, an ATM withdrawal, or a financial advice.

pgfs.auth_plus_capture.reversal

Informative

Load

A previously approved pgfs.auth_plus_capture was fully or partially reversed.

pgfs.auth_plus_capture.standin

Informative

Load

An authorization to fund a user’s GPA and capture those funds was approved by network stand-in processing. Used when the Marqeta platform receives a single-message financial transaction, such as a PIN debit, an ATM withdrawal, or a financial advice.

pgfs.authorization

Actionable

Load

Request for authorization to fund a user’s GPA.

pgfs.authorization.capture

Informative

Load

Funds have been captured for the original authorization.

pgfs.authorization.capture.chargeback

Informative

Unload

A chargeback was performed. Funds have been refunded to the refunds_destination configured on the card product. In the case of JIT Funding, the refunds_destination is set to GATEWAY, which results in the funds being returned to the Program Gateway Funding Source.

pgfs.authorization.capture.chargeback.reversal

Informative

Load

A chargeback was reversed, debiting funds from the funding source.

pgfs.authorization.incremental

Actionable

Load

Request for authorization to fund a user’s GPA for the purpose of increasing the amount of a previous authorization. This method adds to the previous amount rather than replacing it.

pgfs.authorization.reversal

Informative

Load

A previously approved authorization for JIT Funding was fully or partially reversed.

pgfs.authorization.standin

Informative

Load

An authorization to fund a user’s GPA was approved by network stand-in processing.

pgfs.directdeposit.credit

Informative

Load

The Marqeta platform applied a direct deposit credit to the GPA.

pgfs.directdeposit.credit.reversal

Informative

Unload

A previously approved direct deposit credit was fully or partially reversed.

pgfs.directdeposit.debit

Informative

Unload

The Marqeta platform applied a direct deposit debit to the GPA.

pgfs.directdeposit.debit.reversal

Informative

Load

A previously approved direct deposit debit was fully or partially reversed.

pgfs.force_capture

Informative

Load

This method indicates one of the following:

  • Although the GPA had sufficient funds for the original authorization, it had insufficient funds for clearing. In this case, JIT Funding was not performed at authorization, so JIT Funding is forced at clearing time.

  • The merchant force-posted the transaction and funds were provided through JIT Funding.

pfgs.original.credit.authorization

Actionable

Load

Request for authorization to credit the GPA.

pgfs.original.credit.authorization.clearing

Informative

Load

Funds have been cleared for the OCT authorization.

pgfs.original.credit.authorization.reversal

Informative

Unload

A previously approved OCT authorization was fully or partially reversed.

pgfs.original.credit.auth_plus_capture

Actionable

Load

Request for authorization to credit the GPA and capture those funds.

pgfs.original.credit.auth_plus_capture.reversal

Informative

Unload

A previously approved pgfs.original.credit.auth_plus_capture was fully or partially reversed.

pgfs.balanceinquiry

Actionable

n/a

Request for balance information, often the result of a card holder request at an ATM. No funding event.

pgfs.pindebit.chargeback

Informative

Unload

A chargeback was performed. Funds have been refunded to the refunds_destination configured on the card product. In the case of JIT Funding, the refunds_destination is set to GATEWAY, which results in the funds being returned to the Program Gateway Funding Source.

pgfs.pindebit.chargeback.reversal

Informative

Load

A chargeback was reversed, debiting funds from the funding source.

pgfs.refund

Informative

Unload

A merchant refund was performed. Funds have been refunded to the refunds_destination configured on the card product. In the case of JIT Funding, the refunds_destination can only be set to GATEWAY, which results in the funds being returned to the Program Gateway Funding Source.

pgfs.refund.authorization

Actionable

Unload

Request to your JIT gateway for authorization to credit the card holder’s GPA.

pgfs.refund.authorization.capture

Informational

Unload

Request for authorization to credit the card holder’s GPA and capture those funds.

pgfs.refund.reversal

Informative

Unload

The financial impact of a merchant refund was reversed.

The jit_funding object also contains an address_verification object. This object stores address data provided by the purchaser and address data held on the Marqeta platform, as well as the address match determination made by the Marqeta platform. You can use this data to help make funding decisions in response to JIT Funding requests. For more information on how to use this object, see Using AVS with JIT Funding.

JIT Funding requests

The Marqeta platform sends JIT Funding requests to your gateway endpoint. Each request includes an abbreviated form of the related transaction (unless it is a non-financial balance inquiry, in which case there is no associated transaction). The request’s gpa_order.jit_funding object contains the details necessary for JIT Funding, including the amount of requested funding (note that other amount fields within the body might indicate different values).

Note
Each transaction and related JIT Funding request include only a subset of available fields, depending on the merchant, card network, or product/service purchased.

Partial approval

The JIT Funding request message includes the partial_approval_capable field of the associated transaction. This field indicates whether your JIT Funding response can approve some amount less than the requested amount (partial_approval_capable is true) or must approve the entire amount (partial_approval_capable is false). For example, if you receive a JIT Funding request for $100, and partial_approval_capable is true, your response can approve a smaller amount, such as $50. In your response, include the partial approval amount in the jit_funding.amount field, just as you would when approving the whole amount.

Note
Support for partial approval is dependent on the merchant.

Headers

Each JIT Funding request includes the following HTTP headers that inform your system about the details of the incoming request.

Name Description Allowable Values

x-marqeta-request-trace-id

The universally unique identifier of the JIT Funding request.

An existing UUID.

x-marqeta-jit-funding-gateway-version

The version of your JIT Funding gateway.

1.0, 2.0, 3.0

x-marqeta-transactions-model-version

The version of the transaction model returned by the Core API.

1.0, 2.0

The gpa_order.jit_funding object

Fields Description

token

string, required

Identifies the JIT Funding request and response.

Allowable Values:

Matches the funding.gateway_log.transaction_id field of the associated general purpose account (GPA) order. Note that the transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.

method

string, required

Identifies the JIT Funding request type.

Allowable Values:

pgfs.authorization, pgfs.auth_plus_capture, pgfs.authorization.incremental

user_token

OR

business_token

string, required

Identifies the holder of the account to be funded.

Include either a user_token or business_token field.

Allowable Values:

An existing user or business token.

acting_user_token

string, required

Identifies the user who conducted the transaction.

This user can be a child user configured to share its parent’s account balance.

Allowable Values:

An existing user token.

amount

decimal, required

The requested amount of funding.

Note
This field’s value can differ from the transaction’s top-level amount value, which defines the authorization amount. These values differ when the account being funded has a positive account balance. Associated fees also cause these fields to differ.

Allowable Values:

0.00 format

address_verification

object, optional

Contains address verification data consisting of address data entered by the card holder, address data held on the Marqeta platform, and an assertion by the Marqeta platform as to whether the two sets of data match.

Allowable Values:

original_jit_funding_token

string, optional

The token of the first associated JIT Funding message. This token enables you to correlate related JIT Funding messages (that is, those associated with the same GPA order). This field is not included in the first of any set of related messages.

Allowable Values:

An existing JIT Funding message token (from the jit_funding.token field).

The gpa_order.jit_funding.address_verification object

Name Type Required? Description

request

object

No

Contains address verification data provided by the card holder.

issuer

object

No

Contains both address verification data held by the Marqeta platform and an assertion by the Marqeta platform as to whether its address verification data matches that provided by the card holder.

The gpa_order.jit_funding.address_verification.request object

Fields Description

street_address

string, optional

Street address provided by the card holder.

Allowable Values:

40 char max

postal_code

string, optional

Postal code provided by the card holder.

Allowable Values:

9 char max

The gpa_order.jit_funding.address_verification.issuer object

Name Type Required? Description

on_file

object

No

Contains address verification data stored on the Marqeta platform.

response

object

No

Contains an assertion by the Marqeta platform as to whether its address verification data matches that provided by the card holder.

The gpa_order.jit_funding.address_verification.issuer.on_file object

Fields Description

street_address

string, optional

Street address provided by the Marqeta platform.

This field is a concatenation of the address1 and address2 fields associated with the card holder.

Allowable Values:

40 char max

postal_code

string, optional

Postal code provided by the Marqeta platform.

Allowable Values:

9 char max

The gpa_order.jit_funding.address_verification.issuer.response object

Fields Description

code

string, optional

Assertion by the Marqeta platform as to whether its address verification data matches that provided by the card holder. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

memo

string, optional

Free-form comments included in the transaction data for authorization and authorization completion transactions. It is recommended that this field contains additional information about address verification and does not contain PII data.

Allowable Values:

99 char max

Sample request (required fields)

The following sample JIT Funding request contains only required fields. These fields are present in every JIT Funding request.

{
  "type" : "authorization",
  "state" : "PENDING",
  "token" : "198d1132-b34e-4445-a5ca-2e0fe4a55e26",
  "user_token" : "user-158634",
  "acting_user_token" : "user-158634",
  "card_token" : "card-158634",
  "gpa" : {
    "currency_code" : "USD",
    "ledger_balance" : 252.93,
    "available_balance" : 0.00,
    "credit_balance" : 0.00,
    "pending_credits" : 0.00,
    "balances" : {
      "USD" : {
        "currency_code" : "USD",
        "ledger_balance" : 252.93,
        "available_balance" : 0.00,
        "credit_balance" : 0.00,
        "pending_credits" : 0.00
      }
    }
  },
  "gpa_order" : {
    "token" : "b849f8a2-77a6-4745-bbb3-1dd8710427fa",
    "amount" : 29.74,
    "transaction_token" : "198d1132-b34e-4445-a5ca-2e0fe4a55e26",
    "state" : "PENDING",
    "funding" : {
      "amount" : 29.74,
      "source" : {
        "type" : "programgateway",
        "token" : "**********6a19",
        "active" : true,
        "name" : "jit funding source name",
        "is_default_account" : false,
        "created_time" : "2016-11-09T09:36:09Z",
        "last_modified_time" : "2016-01-15T19:38:55Z"
      }
    },
    "funding_source_token" : "**********6a19",
    "jit_funding" : {
      "token" : "0b199f94-2d5c-4fc4-9357-be998eaeebfd",
      "method" : "pgfs.authorization",
      "user_token" : "user-158634",
      "acting_user_token" : "user-158634",
      "amount" : 29.74
    },
    "user_token" : "user-158634",
    "currency_code" : "USD"
  },
  "created_time" : "2017-09-25T23:41:25Z",
  "user_transaction_time" : "2017-09-25T23:41:25Z",
  "amount" : 29.74,
  "currency_code" : "USD",
  "network" : "MASTERCARD",
  "card_acceptor" : {
    "mid" : "4445001899609",
    "mcc" : "5411",
    "name" : "WHOLEFDS EGW 101",
    "city" : "EDGEWATER",
    "state" : "NJ",
    "postal_code" : "07020",
    "country" : "USA",
  },
  "acquirer": {
         "institution_country": "840",
         "institution_id_code": "375321467",
         "retrieval_reference_number": "526051868288",
         "system_trace_audit_number": "676127"
  },
  "card_security_code_verification": {
         "type": "CVV1",
         "response": {
             "code": "0000",
             "memo": "Card security code match"
         }
  },
  "fraud": {
         "network": {
             "transaction_risk_score": 86,
             "account_risk_score": 2
         }
  },
  "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?

Sample request (with selection of optional fields)

The following sample JIT Funding request contains required fields plus a selection of optional objects and fields such as gpa_order.jit_funding.original_jit_funding_token and gpa_order.jit_funding.address_verification.

{
  "type": "authorization.incremental",
  "state": "PENDING",
  "token": "9699f5fc-3516-49c1-93a1-f6a9e6635bdf",
  "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
  "acting_user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
  "card_token": "028b20b2-215f-4ab4-a334-f08d99def0e4",
  "preceding_related_transaction_token": "9b8444db-d4f8-43a7-9eeb-80c0bf90833f",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 60.0,
    "available_balance": 0.0,
    "credit_balance": 0.0,
    "pending_credits": 0.0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 60.0,
        "available_balance": 0.0,
        "credit_balance": 0.0,
        "pending_credits": 0.0
      }
    }
  },
  "gpa_order": {
    "token": "a3abe952-bd25-48b8-8511-7d6350c15bf3",
    "amount": 1.0,
    "transaction_token": "9699f5fc-3516-49c1-93a1-f6a9e6635bdf",
    "state": "PENDING",
    "funding": {
      "amount": 1.0,
      "source": {
        "type": "programgateway",
        "token": "**********d27e",
        "active": true,
        "name": "Program Gateway Funding Source",
        "is_default_account": false,
        "created_time": "2017-08-24T21:52:36Z",
        "last_modified_time": "2017-08-24T21:52:36Z"
      }
    },
    "funding_source_token": "**********d27e",
    "jit_funding": {
      "token": "9f4ec793-2dfc-4a41-aac2-dbdb348f335e",
      "method": "pgfs.authorization.incremental",
      "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
      "acting_user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
      "amount": 1.0,
      "original_jit_funding_token": "2c4f1443-a82b-446f-8fbc-366ddc5c9c9f",
      "address_verification": {
        "request": {
          "street_address": "",
          "postal_code": "94702"
        },
        "issuer": {
          "on_file": {
            "street_address": "",
            "postal_code": "94702"
          },
          "response": {
            "code": "0200",
            "memo": "Address not present and postal code match"
          }
        }
      }
    },
    "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
    "currency_code": "USD"
  },
  "created_time": "2017-09-29T21:35:03Z",
  "user_transaction_time": "2017-09-29T21:35:03Z",
  "settlement_date": "2017-09-29T00:00:00Z",
  "request_amount": 1.0,
  "amount": 1.0,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "network": "MASTERCARD",
  "acquirer_fee_amount": 0,
  "card_acceptor": {
    "mid": "123456890",
    "mcc": "6411",
    "name": "Mareqeta Storefront",
    "address": "330 Central Ave. St.",
    "city": "St. Petersburg",
    "state": "CA",
    "postal_code": "33705",
    "country": "USA"
  },
  "acquirer": {
         "institution_country": "840",
         "institution_id_code": "375321467",
         "retrieval_reference_number": "526051868288",
         "system_trace_audit_number": "676127"
   },
   "card_security_code_verification": {
         "type": "CVV1",
         "response": {
             "code": "0000",
             "memo": "Card security code match"
         }
   },
   "fraud": {
         "network": {
             "transaction_risk_score": 86,
             "account_risk_score": 2
         }
   },
   "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?

JIT Funding responses

Your JIT Funding gateway must respond to each JIT Funding request and either approve or deny the requested funding.

Ensure that your response body adheres to the specifications in this section. You must include all required fields regardless of whether you approve or deny the transaction. Balance inquiries require an additional balances object in the response

Approving or denying the request

Use the following HTTP response codes to indicate whether you approve or deny the funding request.

  • To approve funding for the JIT Funding request: Set the HTTP response code to "200 OK".

  • To deny funding for the JIT Funding request: Set the HTTP response code to "402 Request Failed".

Response body field details

Fields Description

jit_funding

object, required

The top-level element of the response. All other fields are contained within this element.

Allowable Values:

The jit_funding object

Fields Description

token

string, required

Identifies the JIT Funding request and response.

Allowable Values:

Must match request.

method

string, required

Identifies the JIT Funding response type.

Allowable Values:

Must match request.

user_token

OR

business_token

string, required

Identifies the holder of the account to be funded.

Include either a user_token or business_token field.

Allowable Values:

Must match request.

acting_user_token

string, optional

Identifies the user who conducted the transaction.

This user can be a child user configured to share its parent’s account balance.

Allowable Values:

Must match request when present.

amount

decimal, optional

The requested amount of funding.

Allowable Values:

If partial_approval_capable is false, the response amount must match the request amount. If partial_approval_capable is true, the response amount must be equal to or less than the request amount and greater than zero.

Note
The JIT Funding request contains multiple amount fields. Ensure that you use the value from gpa_order.jit_funding.amount. Do not use the value from the top-level amount field or any other amount field because those fields might contain a value different from the gpa_order.jit_funding.amount field. In particular, amount fields will differ if the account being funded has a positive account balance before JIT Funding is requested. Associated fees can also cause amount field values to differ.

original_jit_funding_token

string, optional

The token of the first associated JIT Funding message. This token enables you to correlate related JIT Funding messages (that is, those associated with the same GPA order). This field is not included in the first of any set of related messages.

Allowable Values:

Must match request when present.

address_verification.gateway

object, optional

Contains gateway-held address verification data and the gateway’s assertion as to whether its data matches the data provided by the card holder.

Include this object only if you want to override the assertion provided in the JIT Funding request.

Allowable Values:

balances

object, optional

Contains balance information, by currency.

Allowable Values:

Include this object only in response to a balance inquiry (pgfs.balanceinquiry).

tags

string, optional

A comma-delimited list of tags.

Allowable Values:

255 char max

memo

string, optional

Free-form comments included in the transaction data for authorization and authorization completion transactions. It is recommended that this field contains additional information about the funding event and does not contain PII data.

Allowable Values:

99 char max

The jit_funding.address_verification.gateway object

Name Type Required? Description

on_file

object

No

Contains address verification data held by the gateway.

response

object

No

Contains the gateway’s assertion as to whether its address verification data matches the card holder’s.

The jit_funding.address_verification.gateway.on_file object

Fields Description

street_address

string, optional

Street address provided by the gateway.

Allowable Values:

40 char max

postal_code

string, optional

Postal code provided by the gateway.

Allowable Values:

9 char max

The jit_funding.address_verification.gateway.response object

Fields Description

code

string, optional

Gateway’s assertion as to whether the address verification data provided by the gateway and card holder match. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

memo

string, optional

Free-form comments included in the transaction data for authorization and authorization completion transactions. It is recommended that this field contains additional information about address verification and does not contain PII data.

Allowable Values:

99 char max

The jit_funding.balances object

When responding to balance inquiries, you must include the jit_funding.balances object containing fields matching the request’s gpa.balances object. The balances object contains one or more objects for each currency of funds held by the associated account. For example, if an account only holds a balance in USD, there is one subobject: USD.

You must populate the balances object with the correct amounts from your ledger. You should not include the amount field in your response.

Note
Your gateway must handle scenarios where card holders make purchases and balance inquiries in quick succession.

Each currency-specific subobject of jit_funding.balances contains the following fields:

Fields Description

currency_code

string, required

The 3-character ISO 4217 currency type of the balance.

ledger_balance

string, optional

Authorized funds that are currently on hold, but not yet cleared.

available_balance

string, required

The ledger balance minus any authorized (but not yet cleared) transactions. Also known as the card holder’s purchasing power. If you are using JIT Funding, this balance is usually equal to $0.00.

credit_balance

string, optional

Not currently used.

pending_credits

string, optional

ACH loads that have been accepted, but for which the funding time has not yet elapsed.

Sample response for authorizations

{
  "jit_funding": {
    "token": "b0a889ec-d7e2-4744-bc09-aa86b0738500",
    "method": "pgfs.authorization",
    "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
    "amount": "1.00",
    "address_verification": {
      "gateway": {
        "on_file": {
          "street_address": "199 Elm Street Apt #3",
          "postal_code": "94612"
        },
        "response": {
          "code": "0100",
          "memo": "Address and postal code match"
        }
      }
    },
    "original_jit_funding_token": "a1a879ec-d7e2-4744-rc08-ca24b0738537",
    "tags": "groceries, 77.44, whole foods",
    "memo": "Order # 12345 – Funding for employee for 77.44 for employee R.Smith. 77.44 for groceries at Whole Foods"
  }
}

Is this helpful?

Sample response for balance inquiries

{
  "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,
        "credit_balance" : 0.00,
        "pending_credits" : 0.00
      }
    }
  }
}

JIT Funding notifications

The transaction that triggered the JIT Funding request and all associated transactions are sent to your system as webhook notifications. The JIT Funding notification body contains the entire transaction.

To implement JIT Funding notifications, you must complete the following tasks:

  • Set up a webhook endpoint in your system to receive JIT Funding notifications.

  • Respond to each notification message with an HTTP response code of "200 OK" and an empty response body. (The Marqeta platform resends the message until it receives the appropriate response.)

You should use JIT Funding notifications to validate that the Marqeta platform receives and correctly processes each of your JIT Funding responses. Doing so safeguards against a situation where the Marqeta platform times out because of a delayed JIT Funding response and declines an authorization for which you already approved JIT Funding. In a case such as this, you need to know that the authorization was not approved and ensure that your card holder is not debited for the transaction.

The gpa_order.jit_funding object

Fields Description

token

string, required

Identifies the JIT Funding notification.

Allowable Values:

Matches the funding.gateway_log.transaction_id field of the associated GPA order. Note that the transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.

method

string, required

Identifies the JIT Funding notification type.

Allowable Values:

pgfs.adjustment.credit, pgfs.auth_plus_capture.reversal, pgfs.authorization.capture, pgfs.authorization.capture.chargeback.reversal, pgfs.authorization.reversal, pgfs.force_capture, pgfs.directdeposit.credit, pgfs.directdeposit.debit.reversal

user_token

OR

business_token

string, required

Identifies the holder of the account that was funded.

Either a user_token or business_token field is present, not both.

Allowable Values:

An existing user or business token.

acting_user_token

string, required

Identifies the user who conducted the transaction.

This user can be a child user configured to share its parent’s account balance.

Allowable Values:

An existing user token.

amount

decimal, required

The requested amount of funding.

Note
This field’s value can differ from the transaction’s top-level amount field or any other amount field within the transaction. In particular, these fields will differ if the account being funded already has a positive account balance. Associated fees can also cause these fields to differ.

Allowable Values:

0.00 format

address_verification

object, optional

Contains address verification data consisting of address data entered by the card holder, address data held by the Marqeta platform, and an assertion by the Marqeta platform as to whether the two sets of data match.

Allowable Values:

original_jit_funding_token

string, optional

The token of the first associated JIT Funding message. This enables you to correlate related JIT Funding messages (that is, those associated with the same GPA order). This field is not included in the first of any set of related messages.

Allowable Values:

An existing JIT Funding message token (from the jit_funding.token field).

incremental_authorization_jit_funding_tokens

string, optional

An array of tokens referencing the jit_funding.token field of all previous associated pgfs.authorization.incremental JIT Funding requests. This field enables you to ascertain the final transaction amount when the original amount was incremented. It is present in JIT Funding notifications of type pgfs.authorization.capture and pgfs.authorization.reversal (for partial reversals only) if the amount of the initial authorization was increased by way of a pgfs.authorization.incremental JIT Funding request.

Allowable Values:

An array of existing JIT Funding request tokens (from the jit_funding.token field).

The gpa_order.jit_funding.address_verification object

Name Type Required? Description

request

object

No

Contains address verification data provided by the card holder.

issuer

object

No

Contains both address verification data held by the Marqeta platform and an assertion by the Marqeta platform as to whether its address verification data matches that provided by the card holder.

The gpa_order.jit_funding.address_verification.request object

Fields Description

street_address

string, optional

Street address provided by the card holder.

Allowable Values:

40 char max

postal_code

string, optional

Postal code provided by the card holder.

Allowable Values:

9 char max

The gpa_order.jit_funding.address_verification.issuer object

Name Type Required? Description

on_file

object

No

Contains address verification data held by the Marqeta platform.

response

object

No

Contains an assertion by the Marqeta platform as to whether its address verification data matches that provided by the card holder.

The gpa_order.jit_funding.address_verification.issuer.on_file object

Fields Description

street_address

string, optional

Street address provided by the Marqeta platform.

This field is a concatenation of the address1 and address2 fields associated with the card holder.

Allowable Values:

40 char max

postal_code

string, optional

Postal code provided by the Marqeta platform.

Allowable Values:

9 char max

The gpa_order.jit_funding.address_verification.issuer.response object

Fields Description

code

string, optional

Assertion by the Marqeta platform as to whether its address verification data matches that provided by the card holder. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

memo

string, optional

Free-form comments included in the transaction data for authorization and authorization completion transactions. It is recommended that this field contains additional information about address verification and does not contain PII data.

Allowable Values:

99 char max

The gpa_order_unload.jit_funding object

Fields Description

token

string, required

Identifies the JIT Funding notification.

Allowable Values:

Matches the funding.gateway_log.transaction_id field of the associated GPA order. Note that the transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.

method

string, required

Identifies the JIT Funding notification type.

Allowable Values:

pgfs.adjustment.debit, pgfs.authorization.capture.chargeback, pgfs.refund, pgfs.refund.reversal pgfs.directdeposit.debit, pgfs.directdeposit.credit.reversal

user_token

OR

business_token

string, required

Identifies the holder of the account that was JIT funded.

Either a user_token or business_token field is present.

Allowable Values:

An existing user or business token.

acting_user_token

string, required

Identifies the user who conducted the transaction.

This user can be a child user configured to share its parent’s account balance.

Allowable Values:

An existing user token.

amount

decimal, required

The requested amount of JIT funding.

Note
This field’s value can differ from the transaction’s top-level amount field or any other amount field within the transaction. In particular, these fields will differ if the account being funded already has a positive balance. Associated fees can also cause these fields to differ.

Allowable Values:

0.00 format

original_jit_funding_token

string, optional

The token of the first associated JIT Funding message. This enables you to correlate related JIT Funding messages (that is, those associated with the same GPA order). This field is not included in the first of any set of related messages.

Allowable Values:

An existing JIT Funding message token (from the jit_funding.token field).

Sample notification

{
     "type": "authorization",
     "state": "PENDING",
     "token": "3fce1245-6fc8-4da6-aab2-0fb43b8a5c85",
     "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
     "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
     "card_token": "72e72093-f7cb-45fc-aec0-35523eb52c15",
     "gpa": {
         "currency_code": "USD",
         "ledger_balance": 10.00,
         "available_balance": 0.00,
         "credit_balance": 0.00,
         "pending_credits": 0.00,
         "impacted_amount": -10.00,
         "balances": {
             "USD": {
                 "currency_code": "USD",
                 "ledger_balance": 10.00,
                 "available_balance": 0.00,
                 "credit_balance": 0.00,
                 "pending_credits": 0.00,
                 "impacted_amount": -10.00
             }
         }
     },
     "gpa_order": {
         "token": "097f4264-54f0-4c1d-8f5c-a85b2f83d787",
         "amount": 10.00,
         "created_time": "2018-07-10T18:13:26Z",
         "last_modified_time": "2018-07-10T18:13:26Z",
         "transaction_token": "0ca8d264-6f6b-46fa-a6f7-21ec6342a76e",
         "state": "PENDING",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 10.00,
             "source": {
                 "type": "programgateway",
                 "token": "**********4ebf",
                 "active": true,
                 "name": "PGFS for simulating transactions",
                 "is_default_account": false,
                 "created_time": "2018-07-10T18:13:25Z",
                 "last_modified_time": "2018-07-10T18:13:25Z"
             },
             "gateway_log": {
                 "order_number": "3fce1245-6fc8-4da6-aab2-0fb43b8a5c85",
                 "transaction_id": "your-jit-funding-token",
                 "message": "Approved or completed successfully",
                 "duration": 244,
                 "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"
                         }
                     }
                 }
             }
         },
         "funding_source_token": "**********4ebf",
         "jit_funding": {
             "token": "b6086727-1513-419e-8b11-c550572274ce",
             "method": "pgfs.authorization",
             "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
             "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
             "amount": 10.00
         },
         "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
         "currency_code": "USD"
     },
     "duration": 426,
     "created_time": "2018-07-10T18:13:26Z",
     "user_transaction_time": "2018-07-10T18:13:26Z",
     "settlement_date": "2018-07-10T00:00:00Z",
     "request_amount": 10.00,
     "amount": 10.00,
     "issuer_interchange_amount": 0,
     "currency_code": "USD",
     "approval_code": "736660",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "acquirer": {
         "system_trace_audit_number": "035956"
     },
     "user": {
         "metadata": {}
     },
     "card": {
         "metadata": {}
     },
     "card_security_code_verification": {
         "type": "CVV1",
         "response": {
             "code": "0000",
             "memo": "Card security code match"
         }
     },
     "fraud": {
         "network": {
             "transaction_risk_score": 86,
             "account_risk_score": 2
         }
     },
     "card_acceptor": {
         "mid": "11111",
         "mcc": "6411",
         "name": "Chicken Tooth Music",
         "street_address": "111 Main St",
         "city": "Berkeley",
         "state": "CA",
         "postal_code": "94702",
         "country_code": "USA"
     },
     "pos": {
         "partial_approval_capable": true,
         "purchase_amount_only": false,
         "is_recurring": false
     }
 }

Is this helpful?

Reconciliation with custom mapping

Through customization of the JIT Funding response, you can facilitate end-to-end reconciliation of specific activities in your system that are related to JIT Funding.

The JIT Funding response originates from your system. The response contains two optional fields that you can use to inject custom metadata from your system into your JIT Funding-enabled authorization and authorization completion transactions. This mechanism enables you to map elements of your system (such as order numbers, invoice numbers, loan identifiers) to purchases (as represented by transactions).

Note
These two optional fields only appear in the transaction notifications for certain transaction events: authorizations and authorization completion.

The following sample code snippet shows these two optional fields in the JIT Funding response. The tags field is intended for holding a comma-delimited list of tags, whereas the memo field is intended for holding a free-form note containing additional information you would like included in your transaction data (including PII data is not recommended):

{
  "jit_funding": {
    ...
    "tags": "travel, gas, 32.45, vegas",
    "memo": "Order # 12345 -  Funding for employee M.Jones. $32.45 in gas for conference in Vegas."
  }
}

Is this helpful?

The authorization or authorization completion transaction stores the custom metadata contained in these fields for access throughout the transaction’s lifecycle. You can access this metadata by way of webhook notifications or by querying the /transactions endpoint (see Webhooks and Transactions). The following sample code snippet shows these fields in the context of a transaction:

{
  "token" : "8f5067b5-9c04-4ecb-818e-3c215182b935",
  "type" : "authorization",
  "state" : "PENDING",
  "duration" : 502,
  "amount" : 9.88,
  "response" : {
    "code" : "0000",
    "memo" : "Approved or completed successfully"
  },
  // ... snip ...
  "gpa_order" : {
    // ... snip ...
      "gateway_log" : {
        "message" : "Approved or completed successfully",
        "duration" : 377,
        "order_number" : "8984484",
        "transaction_id" : "4674c07b-23f7-45a5-bc04-95efdc2fe45b",
        "timed_out" : false,
        "response" : {
          "code" : "200",
          "data" : {
            "jit_funding" : {
              "token" : "4674c07b-23f7-45a5-bc04-95efdc2fe45b",
              "method" : "pgfs.authorization",
              "amount" : 9.88,
              "user_token" : "132076",
              "tags": "travel, gas, 32.45, vegas",
              "memo": "Order # 12345 -  Funding for employee M.Jones. $32.45 in gas for conference in Vegas."
            }
          }
        }
      }
    // ... snip ...
  // ... snip ...
}

Is this helpful?

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.