Swimlanes.io is a free webapp for making sequence diagrams. You simply edit the text on the left and the diagram is updated in real time. You can download your sequence diagrams as images or distribute with a link.
Title: Expense Management Program Management APIs Group: LEGEND Note: **Boxed text** = `Actual money movement` **Dashed lines** --> Webhook notifications **Solid lines** -> Events Yellow boxes = General Note [Yellow boxes with hyperlinks]() = Take the viewer directly to [Marqeta API documentation](https://www.marqeta.com/docs/core-api/introduction) ...:*Helpful Information* end Group: Gateway JIT Configuration (before program launch) Note (first, last): Customer sets up their gateway endpoint for receiving JSON authorization payloads for each transaction Customer->Marqeta: Customer provides Marqeta with program gateway funding source details ...: **Required fields**: *URL, Basic auth username, Basic auth password, Name* Marqeta<->Marqeta: Marqeta configures PGFS object on behalf of Customer Note:[Program Gateway Funding Source](https://www.marqeta.com/docs/core-api/program-gateway-funding-sources) end Group: Virtual Card Product Configuration (before program launch) Note (first, last): Marqeta creates virtual card product based on issuing bank required criteria set for the BIN type (ie bank set default list of blocked MCCs & daily/weekly/monthly/per transaction maximum spend for the program). Note (first, last): Marqeta provides Customer with card product token to reference when they create each user's card that will govern the above rules set by the issuing bank for all issued cards Customer->Marqeta: Get Card Product (Endpoint: /cardproduct) Note: [View Card Product](https://www.marqeta.com/docs/core-api/card-products#_retrieve_card_product) end Group: Issuing Bank Program Funding Customer-> Program Funding Account: `Customer remits payment to the Marqeta program funding account at Issuing Bank` Marqeta-->Customer: *programreserve.credit* webhook sent to notify Customer of successful receipt of funds into reserve Note:[Reserve Credit Webhook](https://www.marqeta.com/docs/core-api/event-types) end Group: Business Account Creation (ie SMB Customer) SMB->Customer: SMB initiates request to utilize virtual card solution via Customer for subscription expense management Customer->Marqeta: Create Business for each SMB customer (Endpoint: /businesses) Note: [Business Creation](https://www.marqeta.com/docs/core-api/businesses#postBusinesses) Customer ->Marqeta: Inject any optional payment specific identifier (i.e. SMB identifier) in business metadata object or as the business token Note: [Business Metadata](https://www.marqeta.com/docs/core-api/businesses#_the_metadata_object) ...:Marqeta will create an account holder group that by default will require all businesses to pass KYB (account_holder_token: **DEFAULT_AHG**) Note[start(end]]: All businesses will be associated with the **DEFAULT_AHG** account_holder_group Note[start(end]]: Businesses will start in an **UNVERIFIED** state in the businesses.state field Note[start,end]: [Perform KYB](https://www.marqeta.com/docs/core-api/kyc-verification#_perform_kyc) Marqeta-->Customer: *businesstransition.active* webhook event pushed to Customer system when business passes KYC Note: [Business Transition Webhook](https://www.marqeta.com/docs/core-api/event-types#_account_holder_transition_events) end Group: User Account Creation (ie SMB Employee) Customer ->Marqeta: Create User (i.e. SMB Employee) as child user of business parent (Endpoint: /users) Note: [User Creation](https://www.marqeta.com/docs/core-api/users) Customer ->Marqeta: Inject any optional payment specific identifier (i.e. SMB Employee identifier) in user metadata object or as the user token Note: [User Metadata](https://www.marqeta.com/docs/core-api/users#_the_metadata_object) Customer->Marqeta: Create Parent/Child Relationship between Business & User (Endpoint: /users) Note: [Parent/Child Relationship](https://www.marqeta.com/docs/developer-guides/about-account-holders#_parent_child_relationships) Note [start,end]: Set parent_token to the token created in the business creation Note [start,end]: Set uses_parent_account to FALSE if using JIT ...:Marqeta will create an account holder group that you will reference when you create users to avoid KYC on the SMB employee & will automatically activate users upon creation (account_holder_token: **no_kyc_required**) Note[start(end]]: All users will be associated with the **no_kyc_required** account_holder_group Note[start(end]]: Users will start in an **ACTIVE** state in the users.state field end Group: Virtual Card Creation Customer->Marqeta: Create Virtual Card for SMB employee Note:[Virtual Card Creation](https://www.marqeta.com/docs/core-api/cards) Customer->Marqeta: Inject any optional payment specific identifier (i.e. supplier/invoice identifier) in card metadata object Note: [Card Metadata](https://www.marqeta.com/docs/core-api/cards#_the_metadata_object) Note{start,end}: When cards are personalized with an name, OFAC is required. Note[start(end]]: Virtual cards will start in an **ACTIVE** state in the state field Note[start(end]]: Virtual cards will start in a **DIGITALLY_PRESENTED** fulfillment status in the card fulfillment_status field end Group: Virtual Card Presentment Note: Non PCI Level 1 certified customers: Customer->SMB Employee: Customer exposes VC details to SMB Employee using Marqeta.JS Note:[Marqeta.JS](https://www.marqeta.com/docs/developer-guides/using-marqeta-js) ...:The /cards endpoint will only expose the last 4 PAN of cards. To inject the PCI sensitive virtual card details, you will need to leverage Marqeta.JS. Note:PCI Level 1 certified customers: Note: [Show PAN/CVV](https://www.marqeta.com/docs/core-api/cards#_query_parameters) ...:Use the query parameters, “show_pan” and “show_cvv_number” to true to present virtual card details. The card fulfillment state will transition to “DIGITALLY_PRESENTED”. end Group: Physical Card Creation Customer->Marqeta: Create Physical Card (Endpoint: /cards) and reference physical card product Note:[Physical Card Creation](https://www.marqeta.com/docs/core-api/cards) Customer->Marqeta: Inject any optional card specific identifier in card metadata object or as the card token Note: [Card Metadata](https://www.marqeta.com/docs/core-api/cards#_the_metadata_object) Note[start(end]]: Physical cards will start in an **UNACTIVATED** state in the state field Note[start(end]]: Physical cards will start in an **ISSUED** fulfillment status in the card fulfillment_status field end Group: Physical Card Delivery Customer->SMB Employee: Physical card delivered to Employee End Group: Physical Card Activation Note: Non PCI Level 1 certified customers: SMB Employee->Customer: Employee activates physical card via secure iFrame widget embedded in customer application Note: [Activation Widget](https://www.marqeta.com/docs/developer-guides/using-activate-card-and-set-pin-widgets) ...:Activation Widget is required to stay PCI compliant with physical card activation, unless you are PCI Level 1 certified. We also have an IVR service to enable physical card activation via a configurable IVR tool if you decide not to use the Activation Widget. Note: PCI Level 1 certified customers: Note: [Activate Card](https://www.marqeta.com/docs/core-api/cards#_create_card_transition) ...:Use /cardtransitions to transition the card from “UNACTIVATED” to “ACTIVE” state at your discretion. end Group: Payment Controls Configured in Customer Gateway SMB<->Customer: SMB customer provides Customer with supplier payment details Customer<->Customer: Customer implements control within their gateway rules for each supplier payment end Group: Supplier Payment Authorization SMB Employee->Supplier: SMB Employee presents VC details to supplier for payment Supplier ->Card Network: Authorization Card Network -> Marqeta: Authorization Marqeta -> Marqeta: Authorization process Note [start, end]: Marqeta runs authorization against Issuing Bank's required controls (includes bank restricted MCCs & maximum daily/monthly/per transaction spend restrictions) Marqeta->Customer: JIT Auth request for $X sent to Customer gateway endpoint note:[JIT Funding Request](https://www.marqeta.com/docs/core-api/gateway-jit-funding-messages#_the_jit_funding_object) ...:3 second SLA for response Note{start,end}: **Customer confirms user's available balance exceeds authorization amount & merchant data matches** Customer->Marqeta: Customer sends approval response & account is loaded from reserve funds Note: [JIT Funding Response](https://www.marqeta.com/docs/core-api/gateway-jit-funding-messages#_jit_funding_responses) Marqeta -> Card Network: Approved Marqeta --> Customer : *transaction.authorization* Webhook note: [Authorization Webhooks](https://www.marqeta.com/docs/core-api/event-types#_transaction_events) Card Network -> Supplier: Approved Note{start,end}: **Customer uses authorization webhook to update their customer's available balance to adjust for the approved authorization amount** note: [Ledger Management](https://www.marqeta.com/docs/developer-guides/ledger-management-with-jit-funding) end Group: Settlement Supplier->Supplier: Batch capture initiated Supplier->Card Network: Clearing initiated Card Network->Marqeta: Clearing file received Marqeta --> Customer: *transaction.authorization.clearing* Webhook note: [Clearing Webhooks](https://www.marqeta.com/docs/core-api/event-types#_transaction_events) Note{start,end}: **Customer uses clearing webhook to update their user's current balance to adjust for the approved settlement amount** note: [Ledger Management](https://www.marqeta.com/docs/developer-guides/ledger-management-with-jit-funding) End Group: Net 30 Day Repayment Customer->SMB: `Customer collects monthly card spend from SMB according to repayment terms` end Group: Program Funding Account Replenishment Customer->Marqeta: Customer pulls reserve balance debits/credits from the /balances endpoint note:[Reserve Transactions](https://www.marqeta.com/docs/core-api/balances#_list_reserve_account_transactions) Customer->Marqeta: Customer pulls beginngin/ending reserve balance from the /balances endpoint note:[Reserve Balances](https://www.marqeta.com/docs/core-api/balances#_retrieve_reserve_account_balances) Customer-> Program Funding Account: `Customer remits additional payment to the Marqeta program funding account` end Group: Business Management Customer->Marqeta: Suspend/Close Business Account Note: [Transition Business](https://www.marqeta.com/docs/core-api/businesses#_create_business_transition) Marqeta-->Customer: *businesstransition* webhook event pushed to Customer system Note: [Business Transition Webhook](https://www.marqeta.com/docs/core-api/event-types#_account_holder_transition_events) end Group: User Management Customer->Marqeta: Suspend/Close User Account Note: [Transition User](https://www.marqeta.com/docs/core-api/users#_create_user_transition) Marqeta-->Customer: *usertransition* webhook event pushed to Customer system Note: [User Transition Webhook](https://www.marqeta.com/docs/core-api/event-types#_account_holder_transition_events) end Group: Physical Card Management Group: Damaged Card ...: If a card is damaged, reissue the card. A reissued card has the same PAN as the old card but a new CVV2 and expiration date. Customer->Marqeta: Reissue Card Note:[Physical Card Creation](https://www.marqeta.com/docs/core-api/cards#create_card) Note[start,end]: Set the reissue_pan_from_card_token field to the value of the old card’s token field. This action creates a new card with the same PAN as the old card but with a new CVV2 and new expiration date end Group: Lost or Stolen Card Customer->Marqeta: Terminate Card and set the state field to TERMINATED. Note: [Terminate Card](https://www.marqeta.com/docs/core-api/cards#_create_card_transition) Marqeta->Customer: *cardtransition* webhook event pushed to customer system with SUSPENDED state Note: [Card Transition Webhook](https://www.marqeta.com/docs/core-api/event-types#_account_holder_transition_events) end end Group: Optional Reporting APIs (excluding webhooks) Customer->Marqeta: Customer pulls transaction data from the /transactions endpoint note:[Transactions](https://www.marqeta.com/docs/core-api/transactions) end Group: Sandbox Simulations Note [start,end]]:[**authorization**](https://www.marqeta.com/docs/core-api/simulating-transactions#_simulate_authorization): An authorization occurs when funds are put on hold due to card usage Note [start,end]]:[**authorization.clearing**](https://www.marqeta.com/docs/core-api/simulating-transactions#_simulate_clearing_or_refund): A clearing completes an authorization Note [start,end]]:[**authorization.advice**](https://www.marqeta.com/docs/core-api/simulating-transactions#_simulate_authorization_advice): An authorization advice allows an amount to be decreased after the authorization. Replaces the amount of an existing authorization. Note [start,end]]:[**authorization.incremental**](https://www.marqeta.com/docs/core-api/simulating-transactions#_simulate_reversal): Increases the amount of a previous authorization by adding to it without replacing it. Note [start,end]]:[**authorization.reversal**](https://www.marqeta.com/docs/core-api/simulating-transactions#_simulate_reversal) : A reversal occurs when a merchant cancels a transaction after the authorization succeeds but before the clearing process occurs. A reversal releases the hold that was placed on account funds by an authorization, thus returning the funds to the account. Reversals are before clearing/settlement. Note [start,end]]:[**refund**](https://www.marqeta.com/docs/core-api/simulating-transactions#_simulate_clearing_or_refund): A refund occurs when a cardholder requests that the merchant return funds from a previous transaction after the clearing process has completed. end