DOCS

New!

/

20 minute read

August 3, 2019

Event Types

The Marqeta platform supports event notifications for these types of events:

  • Account holder transition events

  • Bill configuration and payment transition events

  • Card transition events

  • Case transition events

  • Chargeback transition events

  • Commando Mode transition events

  • Digital wallet token transition events

  • Transaction events

The type field further categorizes an event notification.

Note
For more information on notifications, see Webhooks Overview.

Account holder transition events

Account holder transition events include activities such as a user or business being created, suspended, or closed. These activities transition a user’s or business’s status.

Account holder transition notifications contain detailed information about the events. They are sent as account holder transition events occur.

Each notification contains a status field that categorizes the account holder transition event. The following table describes each account holder status. Values in the Status column are the literal values of the notification’s status field. When configuring a webhook to capture these events, you must prefix this with usertransition or businesstransition (for example, usertransition.active).

Status Description

unverified

User/business was created in an unverified status due to KYC.

limited

User/business was created in a limited status due to KYC.

active

User/business was created in an active status due to KYC, or passed KYC after being unverified or limited.

suspended

User/business was suspended.

closed

User/business was closed.

Account holder transition notifications are structured as an array within a users or businesses element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a usertransition or businesstransition object returned by the /usertransitions and /businesstransitions endpoints, respectively.

The following example shows a notification message containing a business transition notification, indicating the business was closed.

{
  "businesstransitions": [
    {
      "token": "90f93e95-e03a-4fe3-baeb-0cde1e9db665",
      "status":  "CLOSED",
      "reason_code": "14",
      "channel": "API",
      "created_time": "2018-02-22T19:36:00Z",
      "last_modified_time": "2018-02-22T19:36:00Z",
      "business_token": "1369020d-8e2c-43ff-b957-72676a791e31"
    }
  ]
}

Is this helpful?

For more information about the usertransitions object, see Users. For more information about the businesstransitions object, see Businesses.

Bill configuration and payment transition events

Bill configuration and payment transition events include the following activities:

  • billconfigurationaccounttransition – Creating a biller account association or transitioning an existing association to a new status.

  • billconfigurationaccountupdate – Updating a biller account balance or transitioning the connectivity object of a biller account association to a new status.

  • billconfigurationsubscriptiontransition – Updating a biller account subscription to a new status.

  • billpaymenttransition – Transitioning a bill payment to a new status.

Notifications are sent as the events occur and contain detailed information about the events. Multiple notifications can be included in a single notification message. Each notification contains a status field and other data associated with the transition. For example, billconfigurationaccountupdate events include the new status of the biller account association’s connectivity object and the latest balance for the biller account.

The following tables describe transition events related to bill payments. When configuring a webhook to capture a specific type of event, you must prefix the status with the event type (billconfigurationaccounttransition.deactivated, for example).

Bill configuration account transition events

The following table describes the possible values of the status field within a billconfigurationaccounttransition event.

Status Description

pending

Account details of the user are being validated.

active

Account details have been validated, and the biller account is linked to the user.

deactivated

The account association is deactivated.

suspended

The account association is suspended.

The following example shows a billconfigurationaccounttransition.active event.

{
  "billconfigurationaccounttransitions": [
    {
      "name": "Account Name df3a43",
      "token": "c55ff651-7982-4c1e-ab58-a854dbd23d4e",
      "user_token": "e1635be5-8dbb-488e-8ece-8926f8f9b892",
      "biller_token": "21fc715f-7521-4333-a573-0ef0679ee27a",
      "account_number": "*****0123",
      "status": "ACTIVE",
      "balance": 500,
      "balance_due_date": "2019-02-11",
      "balance_updated_time": "2019-02-11T17:39:24Z",
      "currency_code": "USD",
      "payer_data": {
        "birth_date": "1988-02-23",
        "phone_number": "6065481466",
        "first_name": "Marq",
        "last_name": "Eta",
        "city": "Donaldhaven",
        "state": "CO"
      },
      "connectivity": {
        "status": "SYNCED"
      },
      "created_time": "2019-02-11T17:39:21Z",
      "last_modified_time": "2019-02-11T17:39:25Z"
    }
  ]
}

Is this helpful?

Bill configuration account update events

When creating a new biller account association with a biller that provides balance updates, the Marqeta platform sends notifications (billconfigurationaccountupdate.*) that include a connectivity object, which indicates the status of the connection. The following table describes the possible values of the connectivity.status field.

Status Description

syncing

The biller account balance is being synced.

wating_for_mfa

The biller account balance sync is pending a response to a multi-factor authentication challenge.

synced

The biller account balance is synced.

error

An error occurred while updating the biller account balance.

Once the biller account balance is synced, the Marqeta platform sends notifications that include the biller account balance.

The following example shows a billconfigurationaccountupdate.connectivity.syncing event.

{
  "billconfigurationaccountupdates": [
    {
      "name": "Account Name df3a43",
      "token": "c55ff651-7982-4c1e-ab58-a854dbd23d4e",
      "user_token": "e1635be5-8dbb-488e-8ece-8926f8f9b892",
      "biller_token": "21fc715f-7521-4333-a573-0ef0679ee27a",
      "status": "PENDING",
      "currency_code": "USD",
      "payer_data": {
        "birth_date": "1988-02-23",
        "phone_number": "6065481466",
        "city": "Donaldhaven",
        "state": "CO"
      },
      "connectivity": {
        "status": "SYNCING"
      },
      "created_time": "2019-02-11T17:39:21Z",
      "last_modified_time": "2019-02-11T17:39:24Z"
    }
  ]
}

Is this helpful?

Bill configuration subscription transition events

The following table describes the possible values of the status field within a billconfigurationsubscriptiontransition event.

Status Description

ACTIVE

The biller account subscription is initiating bill payments as configured.

CANCELLED

The biller account subscription was ended.

EXPIRED

The biller account subscription ended because the expiration date or number of payments was reached.

ERROR

An error occurred and the biller account subscription is not initiating bill payments.

The following example shows a billconfigurationsubscriptiontransition.cancelled event.

{
  "billconfigurationsubscriptiontransitions": [
    {
      {
        "token: "my_subscription_transition_token",
        "subscription_token": "my_subscription_token",
        "user_token": "my_user_token",
        "status": "CANCELLED,"
        "reason": "Cancelled bill payments",
        "channel": "API",
        "created_time": "2018-04-16T14:02:03Z"
}

Is this helpful?

Bill payment transition events

The following table describes the possible values of the status field within a billpaymenttransition event.

Status Description

rejected

The bill payment was rejected due to a failed precondition, such as the user was not found or there were insufficient funds in the account associated with the user to fund the bill payment.

initiated

There were sufficient funds in the account associated with the user to fund the bill payment, and the payment details could be verified.

sent

The bill payment is is being processed by the card network.

confirmed

The bill payment is being processed by the biller.

reversed

The biller could not process the bill payment, or the payment was reversed by the user.

applied

The bill payment was successfully paid to the biller.

The following example shows a billpaymenttransition.applied event.

{
  "billpaymenttransitions": [
    {
      "token": "3c2d356a-8c3f-4823-a718-00e1978799be",
      "user_token": "8d60d348-f38c-40d9-aa99-2e231e20013e",
      "amount": 10.0,
      "currency_code": "USD",
      "status": "APPLIED",
      "created_time": "2019-02-03T17:30:09Z"
    }
  ]
}

Is this helpful?

For more information about the billconfiguration object, see Bill Configurations. For more information about the billpayment object, see Bill Payments.

Card transition events

Card transition events include activities such as a card being activated/deactivated, ordered, or shipped. From a technical point of view, they are activities that cause the transition of a card’s state or fulfillment_status field.

Card transition notifications are sent as card transition events occur and contain detailed information about the events.

Each notification contains a type field that categorizes the card transition event. The following table describes each card transition event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with cardtransition (for example, cardtransition.fulfillment.issued).

Type Description

fulfillment.digitally_presented

Card was digitally presented using the /cards/{token}/showpan API.

fulfillment.issued

Card was created/issued.

fulfillment.ordered

Card was ordered from card fulfillment provider.

fulfillment.rejected

Card was rejected by card fulfillment provider.

fulfillment.reordered

Card was reordered from card fulfillment provider.

fulfillment.shipped

Card was shipped by card fulfillment provider.

state.activated

Card was activated.

state.reinstated

Card was re-instated from a suspended state.

state.suspended

Card was suspended.

state.terminated

Card was terminated.

Card transition notifications are structured as an array within a cards element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a cardtransition object returned by the /cardtransitions API endpoint.

The following example shows a notification message containing two card transition notifications: one for the issuance of a card, and one for the activation of that card.

{
  "cards": [
    {
      "token": "my_card_transition_token",
      "state": "ACTIVE",
      "reason": "I want to use this card.",
      "channel": "API",
      "validations": {
        "user": {
          "phone": false,
          "ssn": false,
          "birth_date": true
        }
      },
      "type": "state.activated",
      "pan": "111111______0117",
      "expiration": "0820",
      "card_token": "my_card_token",
      "user_token": "my_user_token",
      "fulfillment_status": "ISSUED",
      "created_time": "2016-08-30T22:03:35Z",
      "card_product_token": "my_card_product_token",
      "last_four": "0117",
      "expiration_time": "2020-08-31T23:59:59.000Z",
      "pin_is_set": false
    },
    {
      "token": "d7ddfa76-dec1-4c15-81a5-17558f73cc76",
      "state": "UNACTIVATED",
      "reason": "New card",
      "channel": "SYSTEM",
      "validations": {
        "user": {
          "phone": false,
          "ssn": false,
          "birth_date": false
        }
      },
      "type": "fulfillment.issued",
      "pan": "111111______0117",
      "expiration": "0820",
      "card_token": "my_card_token",
      "user_token": "my_user_token",
      "fulfillment_status": "ISSUED",
      "created_time": "2016-08-30T22:01:47Z",
      "card_product_token": "my_card_product_token",
      "last_four": "0117",
      "expiration_time": "2020-08-31T23:59:59.000Z",
      "pin_is_set": false
    }
  ]
}

Is this helpful?

For more information about the cardtransitions object, see Cards.

Case transition events

Case transition events include activities such as a case being opened, readied, or closed. These activities transition the state of a case.

Case transition notifications are sent as case transition events occur and contain detailed information about the events.

Each notification contains a state field that categorizes the case transition event. The following table describes each case transition event. Values in the State column are the literal values of the notification’s state field. When configuring a webhook to capture these events, you must prefix this with casetransition (for example, casetransition.open).

State Description

OPEN

The case was created.

CLOSED

The case was closed.

READY

The case is ready for review.

CHARGEBACK_INITIATED

A chargeback was initiated against the case.

Case transition notifications are structured as an array within a casetransitions object. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a casetransition object returned by the /cases/{token}/transitions/ endpoint (where {token} indicates the case with which the transitions are associated).

The following example shows a notification message containing a case transition notification, indicating a chargeback was initiated.

{
  "casetransitions": [
    {
      "token": "my_casetransition_id1",
      "case_token": "my_case_id",
      "action": "CHARGEBACK_CREDIT",
      "reason_code": "27",
      "created_by": "rgadewar",
      "memo": "Initiating chargeback",
      "assignee": "rgadewar",
      "reason_description": "Smaller Amount",
      "state": "CHARGEBACK_INITIATED",
      "created_time": "2018-03-19T13:22:07Z",
      "last_modified_time": "2018-03-20T09:22:07Z"
    }
  ]
}

Is this helpful?

Chargeback transition events

Chargeback transition events mark the progress of disputes through the arbitration process. From a technical point of view, chargeback transition events cause the transition of a chargeback object’s state field.

The chargeback object represents a completed transaction that has been disputed by the issuer. In order for the dispute to be resolved, the chargeback must pass through an arbitration process consisting of multiple phases. Each phase of the arbitration process is represented by a chargebacktransition object of a particular type. For example, the creation of a new chargeback incidentally creates a chargebacktransition of type initiated. After creating a chargeback, you can explicitly move it from one arbitration phase to another by creating a chargebacktransition of the appropriate type. Chargebacks do not follow a prescribed path through the arbitration process.

Chargeback transition notifications are sent as chargeback transition events occur and contain detailed information about the events.

Each notification contains a type field that categorizes the chargeback transition event. The following table describes each chargeback transition event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with chargebacktransition (for example, chargebacktransition.representment).

Type Description

initiated

The chargeback has been created. Funds to cover the disputed charges have been credited to the card holder’s account if the credit_user field was true or unspecified at the time of creation.

representment

The case is in representment (also known as second presentment). The gateway/acquirer has disputed the chargeback. In some cases representment does not occur.

prearbitration

The case is in pre-arbitration (also known as arbitration chargeback). Upon receipt of a dispute from the gateway/acquirer (representment), the issuer can submit the chargeback a second time, possibly with more or different information. Only relevant chargebacks assume this status.

arbitration

The case is in arbitration. When a gateway/acquirer disputes a chargeback, the issuer can submit the case to the card network for arbitration after either the first or second (pre-arbitration) chargeback. In arbitration, the card network decides who wins the chargeback case.

case.won

The chargeback case is closed; Marqeta won.

case.lost

The chargeback case is closed; Marqeta lost.

network.rejected

The card network rejected the chargeback submission.

written.off.issuer

Can be transitioned to only from case.lost or network.rejected. The chargeback is credited to the GPA of the user or business and Marqeta absorbs the cost.

written.off.program

Can be transitioned to only from case.lost or network.rejected. The chargeback is credited to the GPA of the user or business and the Marqeta customer absorbs the cost through a debit from the program funding source.

Chargeback transition notifications are structured as an array within a chargebacktransitions element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a chargebacktransition object returned by the /chargebacks/transitions API endpoint.

The following example shows a notification message containing two chargeback transition notifications:

{
  "chargebacktransitions": [
    {
      "token": "my_chargeback_transition_11",
      "state": "PREARBITRATION",
      "previous_state": "REPRESENTMENT",
      "channel": "ISSUER",
      "chargeback_token": "my_chargeback_09",
      "reason": "Product not received",
      "transaction_token": "710",
      "created_time": "2017-10-06T23:07:18Z",
      "last_modified_time": "2017-10-06T23:07:18Z",
      "type": "prearbitration"
    },
    {
      "token": "my_chargeback_transition_10",
      "state": "REPRESENTMENT",
      "previous_state": "INITIATED",
      "channel": "ISSUER",
      "chargeback_token": "my_chargeback_08",
      "reason": "Product not received",
      "transaction_token": "708",
      "created_time": "2017-10-05T23:55:20Z",
      "last_modified_time": "2017-10-05T23:55:20Z",
      "type": "representment"
    }
  ]
}

Is this helpful?

For more information about the chargebacks object, see Chargebacks.

Commando Mode transition events

Commando Mode transition events include enabling and disabling a Commando Mode control set for the associated program gateway funding source. These activities transition the current_state.commando_enabled field of a specific Commando Mode control set.

Commando Mode transition notifications are sent as transition events occur and contain detailed information about the events. When configuring a webhook to capture these events, you must prefix the event type (such as enabled or disabled) with commandomodetransition. For example, to capture when a Commando Mode control set is enabled, you must configure a webhook for the commandomodetransition.enabled event.

The following table describes each Commando Mode transition event type.

Type Description

enabled

Indicates that a Commando Mode control set was enabled.

disabled

Indicates that a Commando Mode control set was disabled.

The following example shows a notification message containing a Commando Mode transition notification, indicating the Commando Mode control set was disabled.

{
  "commandomodetransitions": [
    {
      "token": "my_transition",
      "commando_mode_token": "my_commando_mode",
      "transition" {
        "commando_enabled": "false",
        "reason": "Connection restored",
        "channel": "API",
        "username": "my_user"
      },
      "created_time": "2018-05-28T23:21:46Z"
    }
  ]
}

Is this helpful?

For more information about the commandomodes object, see Commando Mode.

Digital wallet token transition events

Digital wallet token transition events include activities such as a digital wallet token being requested, activated, or terminated. From a technical point of view, they are activities that cause the transition of a token’s state or fulfillment_status field.

Digital wallet token transition notifications are sent as digital wallet token transition events occur and contain detailed information about the events.

Each notification contains a type field that categorizes the digital wallet token transition event. The following table describes each digital wallet token transition event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with digitalwallettokentransition (for example, digitalwallettokentransition.fulfillment.requested).

Type Description

fulfillment.requested

Indicates that a token was requested and provisioning is pending.

state.request_declined

Indicates that token provisioning was rejected. The state of the token cannot be further modified.

state.activated

Indicates that the token has been provisioned and is active.

state.suspended

Indicates that the token has been suspended.

state.reinstated

Indicates that the token has been reactivated from a suspended state.

state.terminated

Indicates that the token has been terminated. The state of the token cannot be further modified.

card.swap

A card was activated (the card state transitioned from UNACTIVATED to ACTIVE), and all existing digital wallet tokens owned by the user and having a state of REQUESTED, ACTIVE, or SUSPENDED were moved to the new card.

Note
The token-related event types "token.activation-request" and "token.advice" are categorized as transaction events and are documented in the Transaction Events" section.

Digital wallet token transition notifications are structured as an array within a digitalwallettokentransitions element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a digitalwallettokentransition object returned by the /digitalwallettokentransitions API endpoint.

The following example shows a notification message containing two digital wallet token transition notifications: one requesting a token, and one for the activation of that token.

{
  "digitalwallettokentransitions": [
    {
      "token": "757644f0-d3a4-3275-6b3e-1edf1ccbd05d",
      "digital_wallet_token": {
        "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
      },
      "type": "state.activated",
      "channel": "API",
      "state": "ACTIVE",
      "fulfillment_status": "PROVISIONED",
      "reason": "Passed additional identity verification",
      "created_time": "2017-02-23T18:57:45Z"
    },
    {
      "token": "659654f0-d5e4-4875-8e3e-2ecf1babd03b",
      "digital_wallet_token": {
        "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
      },
      "type": "fulfillment.requested",
      "channel": "TOKEN_SERVICE_PROVIDER",
      "state": "REQUESTED",
      "fulfillment_status": "DECISION_YELLOW",
      "reason": "Additional identity verification required",
      "created_time": "2017-02-23T18:44:21Z"
    }
  ]
}

Is this helpful?

For more information about the digitalwallettokentransitions object, see Digital Wallets Management.

Transaction events

Transaction events include activities such as authorizations, authorization clearings, and refunds. Although you might think of an authorization and authorization clearing as two parts of the same conceptual transaction, the Marqeta platform treats each transaction-related message exchange as a separate transaction event with a unique identifying token.

Transaction notifications are sent in real time as transaction events occur and contain detailed information about the events.

All transaction notifications contain a type field that categorizes the transaction event. The following table lists all possible values for the type field. The table describes each type, indicates the objects potentially included in that transaction type, and lists the transaction types that could potentially complete it. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with transaction (for example, transaction.authorization).

The response.code field describes the outcome of the attempted transaction. For more information on transaction outcomes, see the transaction response codes table on the Transactions page.

Type Description Possibly Completed by Possibly Included Objects

account.funding.authorization

Funds hold for an account funding transaction (AFT). Temporary transaction type.

account.funding.authorization.clearing

account.funding.authorization.clearing

Completes an AFT authorization. Final transaction type.

account.funding.auth_plus_capture

Funds hold for a single-message AFT. Final transaction type.

account.funding.authorization.reversal

Reverses (cancels) an AFT authorization. Final transaction type.

account.funding.auth_plus_capture.reversal

Reverses (cancels) a single-message AFT. Final transaction type.

authorization

Funds hold resultant from card usage, requires settlement. Temporary transaction type.

authorization.advice, authorization.reversal, authorization.reversal.issuerexpiration, authorization.clearing

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

authorization.advice

Updates an existing authorization by replacing the amount. Requires settlement. Must be honored. Temporary transaction type.

authorization.reversal, authorization.reversal.issuerexpiration, authorization.clearing

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

authorization.clearing

Completes an authorization. Final transaction type.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

authorization.clearing.chargeback

Indicates a chargeback has been initiated by Marqeta.

Possible states: INITIATED, PREARBITRATION, ARBITRATION, CASE_WON

Ledger impact: Positive if credit_user is true; no impact if credit_user is false.

authorization.clearing.chargeback.reversal, authorization.clearing.chargeback.completed

gpa, chargeback, user.metadata

authorization.clearing.chargeback.completed

Indicates a chargeback initiated by Marqeta has completed.

Possible states: CASE_WON

Ledger impact: Positive.

gpa, chargeback, user.metadata

authorization.clearing.chargeback.provisional.credit

Used to switch a chargeback from the non-provisional credit to the provisional credit workflow (provides a credit). Final transaction type. Requires settlement.

gpa, chargeback, user.metadata

authorization.clearing.chargeback.provisional.debit

Used to switch a chargeback from the provisional credit to the non-provisional credit workflow (removes the initial credit). Final transaction type. Requires settlement.

gpa, chargeback, user.metadata

authorization.clearing.chargeback.reversal

Indicates a chargeback initiated by Marqeta has been rejected.

Possible states: CASE_LOST, NETWORK_REJECTED

Ledger impact: Negative if credit_user is true; no impact if credit_user is false.

gpa, chargeback, user.metadata

authorization.clearing.chargeback.writeoff

Indicates that either Marqeta or Marqeta’s customer has absorbed the loss of the chargeback to the account holder. Final transaction type.

Possible states: WRITTEN_OFF_PROGRAM, WRITTEN_OFF_ISSUER

Ledger impact: Positive

gpa, chargeback, user.metadata

authorization.clearing.representment

Indicates a merchant has disputed a chargeback initiated by Marqeta.

Possible states: REPRESENTMENT

Ledger impact: Negative if credit_user is true; no impact 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.

gpa, chargeback, user.metadata

authorization.incremental

Increases the amount of a previous authorization by adding to it rather than replacing it. Requires settlement. Temporary transaction type.

authorization.reversal

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

authorization.reversal

Drop/release of authorization not based on elapsed time.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

authorization.reversal.issuerexpiration

Authorization drop initiated by Marqeta due to elapsed time.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

authorization.standin

The authorization was declined by the card network because it did not receive a response from Marqeta. Final transaction type (begins and ends in a state of DECLINED).

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata, digital_wallet_token

billpayment

A bill payment was authorized. The state of the associated transaction object is PENDING. Temporary transaction type.

billpayment.clearing, billpayment.reversal

gpa, acquirer, card_acceptor

billpayment.clearing

A previously authorized bill payment was cleared. The state of the associated transaction object is COMPLETION. Final transaction type.

gpa, acquirer, card_acceptor

billpayment.reversal

A previously authorized bill payment was reversed. The state of the associated transaction object is COMPLETION. Final transaction type.

gpa, acquirer, card_acceptor

directdeposit.credit

The deposit account was credited. The state of the associated direct deposit record is APPLIED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.credit.pending

The deposit account has a pending credit. The state of the associated direct deposit record is PENDING. Temporary transaction type.

directdeposit.credit, directdeposit.credit.reversal, directdeposit.credit.reject

gpa, direct_deposit, user.metadata

directdeposit.credit.reject

A deposit account credit was rejected. The state of the associated direct deposit record is REJECTED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.credit.pending.reversal

A deposit account pending credit was reversed. The state of the associated direct deposit record is REVERSED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.credit.reversal

A deposit account credit was reversed. The state of the associated direct deposit record is REVERSED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.debit

The deposit account was debited. The state of the associated direct deposit record is APPLIED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.debit.pending

The deposit account has a pending debit. The state of the associated direct deposit record is PENDING. Temporary transaction type.

directdeposit.debit, directdeposit.debit.reversal, directdeposit.debit.reject

gpa, direct_deposit, user.metadata

directdeposit.debit.reject

A deposit account debit was rejected. The state of the associated direct deposit record is REJECTED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.debit.reversal

A deposit account debit was reversed. The state of the associated direct deposit record is REVERSED. Final transaction type.

gpa, direct_deposit, user.metadata

directdeposit.debit.pending.reversal

A deposit account pending debit was reversed. The state of the associated direct deposit record is REVERSED. Final transaction type.

gpa, direct_deposit, user.metadata

fee.charge

Fee is assessed to a user.

fee.charge.reversal

gpa, gpa_order, fee_transfer

fee.charge.pending

An authorization with a fee associated is created.

fee.charge.reversal, fee.charge

gpa, gpa_order, fee_transfer

fee.charge.reversal

A transaction and associated fee are reversed

gpa, gpa_order, fee_transfer

gpa.credit

Crediting of funds into a user’s GPA.

gpa, gpa_order

gpa.credit.authorization.billpayment

A Just-In-Time (JIT) Funding authorization for bill payment was initiated. The state of the associated bill payment is INITIATED. Temporary transaction type.

gpa.credit.billpayment, gpa.credit.authorization.billpayment.reversal

gpa.credit.billpayment

Funds were credited into a user’s GPA for bill payment; possible when using JIT Funding. The state of the associated bill payment is CONFIRMED. Final transaction type.

gpa.credit.authorization.billpayment.reversal

gpa.credit.authorization.billpayment (a JIT Funding authorization for bill payment) was reversed. The state of the associated bill payment is REVERSED. Final transaction type.

gpa.credit.authorization

Temporary transaction type.

gpa.credit.pending.reversal, gpa.credit

gpa, gpa_order

gpa.credit.authorization.reversal

Reverses a gpa.credit.authorization (a JIT Funding authorization); possible when using Just-In-Time (JIT) Funding.

gpa, gpa_order

gpa.credit.issueroperator

Admin function to credit funds to any GPA or MSA. Functionally the same as gpa.credit.

gpa, gpa_order, msa_orders, offer_orders

gpa.credit.networkload

Load of funds performed through a card network service such as Visa ReadyLink or Mastercard RePower at a participating merchant location. Starts and ends in a state of COMPLETION.

gpa

gpa.credit.networkload.reversal

Cancels full amount of a load performed through a card network service such as Visa ReadyLink or Mastercard RePower. Permitted only on the same day as the load. Starts and ends in a state of COMPLETION.

gpa

gpa.credit.pending

ACH deposit pending in pending_credits state for GPA. When funding time > 0. Temporary transaction type.

gpa.credit.pending.reversal, gpa.credit

gpa, gpa_order

gpa.credit.pending.reversal

ACH transaction which we thought succeeded has now failed as a result of notification from the ACH processor for the GPA.

gpa, gpa_order

gpa.credit.reversal

Transaction that had been settled/credited has now failed as a result of notification from the processor for the GPA. Could be credit card or ACH.

gpa, gpa_order

gpa.debit

Debiting of funds from a user’s GPA back to a funding source.

gpa

gpa.debit.issueroperator

Admin function to debit funds from any GPA or MSA. Functionally the same as gpa.debit.

gpa, gpa_order, msa_orders, offer_orders

gpa.debit.reversal

Reverses a gpa.debit, thereby moving funds from the funding source back into the GPA. Final transaction type.

gpaorder

msa.credit

Crediting of funds to a user’s MSA.

gpa, msa_orders

msa.credit.pending

ACH deposit pending in pending_credits state for MSA. When funding time > 0. Temporary transaction type.

msa.credit.pending.reversal, msa.credit

gpa, msa_orders, offer_orders

msa.credit.pending.reversal

ACH transaction which we thought succeeded has now failed as a result of notification from the ACH processor for an MSA.

gpa, msa_orders, offer_orders

msa.credit.reversal

Transaction that had been settled/credited has now failed as a result of notification from the processor for an MSA. Could be credit card or ACH.

gpa, msa_orders, offer_orders

msa.debit

Debiting of funds from a user’s MSA back to a funding source.

gpa, msa_orders

original.credit.authorization

A non-finalized original credit transaction (OCT) for crediting a GPA.

Ledger impact: Positive

original.credit.authorization.reversal, original.credit.authorization.clearing

original.credit.authorization.reversal

Reverses the financial impact of an OCT authorization.

Ledger impact: Negative

original.credit.authorization.clearing

Completes an OCT authorization.

Ledger impact: Positive

original.credit.auth_plus_capture

A single-message OCT for crediting a GPA.

Ledger impact: Positive

original.credit.auth_plus_capture.reversal

Reverses the financial impact of a single-message OCT authorization.

Ledger impact: Negative

pindebit

PIN transaction at POS.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata

pindebit.atm.withdrawal

Cash received from ATM.

store, card_acceptor, gpa, user.metadata

pindebit.authorization

A non-finalized PIN debit transaction used in automated fuel dispenser (AFD) scenarios. Temporary transaction type.

pindebit.authorization.clearing, pindebit.reversal

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata

pindebit.authorization.clearing

Completes a pindebit.authorization transaction. Final transaction type.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata

pindebit.authorization.reversal.issuerexpiration

Authorization drop initiated by Marqeta due to elapsed time. Most transactions of this type originate from authorizations at automated fuel dispensers.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata

pindebit.balanceinquiry

Balance inquiry via card network, e.g., ATM. Non-financial transaction.

store, card_acceptor, gpa, user.metadata

pindebit.cashback

PIN transaction at point of sale where cash back is requested/received.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata

pindebit.chargeback

Indicates a PIN-debit chargeback has been initiated by Marqeta.

Possible states: INITIATED, PREARBITRATION, ARBITRATION, CASE_WON

Ledger impact: Positive if credit_user is true; no impact if credit_user is false.

pindebit.chargeback.reversal, pindebit.chargeback.completed

gpa, chargeback, user.metadata

pindebit.chargeback.completed

Indicates a PIN-debit chargeback initiated by Marqeta has completed.

Possible states: CASE_WON

Ledger impact: Positive.

gpa, chargeback, user.metadata

pindebit.chargeback.provisional.credit

Used to switch a PIN-debit chargeback from the non-provisional credit to the provisional credit workflow (provides a credit). Final transaction type. Requires settlement.

gpa, chargeback, user.metadata

pindebit.chargeback.provisional.debit

Used to switch a PIN-debit chargeback from the provisional credit to the non-provisional credit workflow (removes the initial credit). Final transaction type. Requires settlement.

gpa, chargeback, user.metadata

pindebit.chargeback.reversal

Indicates a PIN-debit chargeback initiated by Marqeta has been rejected.

Possible states: CASE_LOST, NETWORK_REJECTED

Ledger impact: Negative if credit_user is true; no impact if credit_user is false.

gpa, chargeback, user.metadata

pindebit.chargeback.writeoff

Indicates that either Marqeta or Marqeta’s customer has absorbed the loss of the PIN-debit chargeback to the account holder. Final transaction type.

Possible states: WRITTEN_OFF_PROGRAM, WRITTEN_OFF_ISSUER

Ledger impact: Positive

gpa, chargeback, user.metadata

pindebit.credit.adjustment

Completes a previous PIN-debit authorization transaction and adjusts the amount to the actual dispensed amount, in case it was less than the withdrawn amount. Final transaction type.

card_acceptor, gpa, gpa_order

pindebit.refund

Refund of a PIN debit transaction.

store, card_acceptor, gpa

pindebit.refund.reversal

The financial impact of a PIN-debit transaction refund has been reversed.

store, card_acceptor, gpa, merchant, gpa_order_unload, user, card

pindebit.reversal

The financial impact of a PIN-debit transaction or PIN-debit authorization has been reversed.

store, card_acceptor, gpa, msa_orders, offer_orders, user.metadata

pindebit.transfer

ATM transfer between a checking and a savings account.

programreserve.credit

The program reserve account was credited.

programreserve.debit

The program reserve account was debited.

pushtocard.debit

The Push-to-Card payment card was debited.

pushtocard.reversal

The Push-to-Card debit was reversed.

refund

Refund of a card holder transaction.

store, card_acceptor, gpa

refund.authorization

A purchase return authorization.

refund.authorization.advice, refund.authorization.reversal refund.authorization.reversal issuerexpiration, refund.authorization.clearing

refund.authorization.clearing

Clearing for a purchase return authorization.

token.activation-request

Request to activate a digital wallet token.

token.advice

Changes the state of a digital wallet token, for example, from REQUESTED to ACTIVE.

transaction.unknown

Unlikely to occur. Helps to identify transaction errors.

transfer.peer

Results from hitting /peertransfers endpoint. Moves money between GPAs.

gpa, peer_transfer

transfer.program

Movement of funds from the card holder’s GPA to the program funding source. Results from using the /programtransfers endpoint.

gpa, programtransfers

The following is a sample transaction notification. The type and amount fields are always returned. Other fields and object groups are conditionally returned. Refer to the preceding table for a list of objects possibly included for each transaction type.

{
  "transactions": [
    {
     "type": "authorization",
     "state": "PENDING",
     "token": "36d04781-d34f-4e0c-b895-2f1af976b565",
     "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
     "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
     "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
     "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": "e899e39f-5f43-4d0f-857d-75608d949908",
         "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": "36d04781-d34f-4e0c-b895-2f1af976b565",
                 "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",
     "settlement_date": "2018-08-21T00:00:00Z",
     "request_amount": 10,
     "amount": 10,
     "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
         }
     },
    "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?

Possible values for cardholder_presence field

Code Description

0

Card holder not present

1

Card holder present

Possible values for card_presence field

Code Description

0

Card not present

1

Card present

For more information about the transactions object, see Transactions.

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.