We regularly make time here on the blog to showcase the event-driven architecture and patterns used by leading API providers. One of the key patterns employed by API providers who are further along in their journey is event types. The defining events that API providers can subscribe to when it comes to platform operations, allowing them to receive push notifications when the events they care about occur. We find the different types of events platforms have defined, and their approach to employing these events paint an important picture that we can all learn from. In this edition of event type coverage, we are focusing on payment API provider Marqeta, who provides four distinct grouping of event types to manage what happens when it comes to payments via their platform.
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.
– 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.
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.
– fulfillment.delivered – Card was delivered by card shipping provider.
– 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.
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.
– 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.
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.
– 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 network for arbitration after either the first or second (pre-arbitration) chargeback. In arbitration, the 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 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.
– authorization – Funds hold resultant from card usage, requires settlement. Temporary transaction type.
– authorization.advice – Updates an existing authorization by replacing the amount. Requires settlement. Must be honored. Temporary transaction type.
– authorization.clearing – Completes an authorization. Final transaction type.
– authorization.clearing.chargeback – Indicates a chargeback has been initiated by Marqeta.
– authorization.clearing.chargeback.completed – Indicates a chargeback initiated by Marqeta has completed.
– 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.
– 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.
– authorization.clearing.chargeback.reversal – Indicates a chargeback initiated by Marqeta has been rejected.
– 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.
– authorization.clearing.representment – Indicates a merchant has disputed a chargeback initiated by Marqeta.
– authorization.incremental – Increases the amount of a previous authorization by adding to it rather than replacing it. Requires settlement. Temporary transaction type.
– authorization.reversal – Drop/release of authorization not based on elapsed time.
authorization.reversal.issuerexpiration – Authorization drop initiated by Marqeta due to elapsed time.
– 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).
– fee.charge – Fee is assessed to a user.
– fee.charge.pending – An authorization with a fee associated is created.
– fee.charge.reversal – A transaction and associated fee are reversed
– gpa.credit – Crediting of funds into a user’s GPA.
– gpa.credit.authorization – Temporary transaction type.
– gpa.credit.authorization.reversal – Reverses a gpa.credit.authorization (a JIT Funding authorization); possible when using Just-In-Time (JIT) Funding.
– gpa.credit.issueroperator – Admin function to credit funds to any GPA or MSA. Functionally the same as gpa.credit.
– gpa.credit.networkload – Load of funds performed through a network service such as Visa ReadyLink or MasterCard RePower at a participating merchant location. Starts and ends in a state of COMPLETION.
– gpa.credit.networkload.reversal – Cancels full amount of a load performed through a 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.credit.pending – ACH deposit pending in pending_credits state for GPA. When funding time > 0. Temporary transaction type.
– 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.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.debit – Debiting of funds from a user’s GPA back to a funding source.
– gpa.debit.issueroperator – Admin function to debit funds from any GPA or MSA. Functionally the same as gpa.debit.
– gpa.debit.reversal – Reverses a gpa.debit, thereby moving funds from the funding source back into the GPA. Final transaction type.
– msa.credit – Crediting of funds to a user’s MSA.
– msa.credit.pending – ACH deposit pending in pending_credits state for MSA. When funding time > 0. Temporary transaction type.
– 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.
– 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.
– msa.debit – Debiting of funds from a user’s MSA back to a funding source.
– pindebit – PIN transaction at POS.
– pindebit.atm.withdrawal – Cash received from ATM.
– pindebit.authorization – A non-finalized PIN debit transaction used in automated fuel dispenser (AFD) scenarios. Temporary transaction type.
– pindebit.authorization.clearing – Completes a pindebit.authorization transaction. Final transaction type.
– pindebit.authorization.reversal.issuerexpiration – Authorization drop initiated by Marqeta due to elapsed time. Most transactions of this type originate from authorizations at automatic fuel dispensers.
– pindebit.balanceinquiry – Balance inquiry via network, e.g., ATM. Non-financial transaction.
– pindebit.cashback – PIN transaction at point of sale where cash back is requested/received.
– pindebit.chargeback – Indicates a PIN-debit chargeback has been initiated by Marqeta.
– 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.
– 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.
– pindebit.chargeback.reversal – Indicates a PIN-debit chargeback initiated by Marqeta has been rejected.
– 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.
– pindebit.refund – Refund of a PIN debit transaction.
– pindebit.refund.reversal – The financial impact of a PIN-debit transaction refund has been reversed.
– pindebit.reversal – The financial impact of a PIN-debit transaction has been reversed.
– 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. – –
– 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.
– transfer.program – Movement of funds from the card holder’s GPA to the program funding source. Results from using the /programtransfers endpoint.
Marqeta provides a pretty robust set of event types we can track on when it comes to tuning into the event-driven architecture in use in the payments API sector. Helping define the meaningful events that impact end-users accounts, credit cards, and the payments they are making. Demonstrating how the leading API providers are evolving their request and response API infrastructure towards a more event-driven way of doing business.
We have a large list of API providers to showcase when it comes to event-driven API architecture. Similar to Marqeta, we will keep documenting the event types they are publishing and putting to work for their platform developers and their end users. With each story, we are documenting the landscape, and at some point, we’ll publish a single list of event types across all of the companies we’ve profiled, providing a comprehensive list of event types to consider. Eventually, we’d like to help steer the conversation around the standardization of event types in use and continue defining a common set of patterns that API providers can use when pushing their event-driven architecture forward.
