Instant Card Transfers

Account holders funding a new deposit account or card typically rely on direct deposit or an ACH transfer from another bank account, both of which can take three to five days to complete. Instant Card Transfers gives account holders a faster alternative: it moves funds between a Marqeta-issued card and an external, non-Marqeta debit or prepaid card over card network rails, so funds are available for spending within seconds instead of days. This guide provides an overview of Instant Card Transfers and the APIs you can use to implement it. At the end of this guide, you should understand:

• What Instant Card Transfers is, and the use cases it supports.
• How to add, view, and manage an external card.
• How to create a transfer, and which transfer_type to use for your use case.
• What to check before a transfer fails because of an ineligible card.
• Where to find the API reference pages for the Transfers and External Cards APIs.

​

What is Instant Card Transfers

Instant Card Transfers connects a Marqeta-issued card to an external card (a debit or prepaid card issued by another financial institution) and lets you move funds between them in real time. A Marqeta customer adds the external card to the Marqeta platform, then uses that card as the source or destination for a transfer. Instant Card Transfers uses Cross River Bank (CRB) as the acquirer for the external card side of each transfer. Because the transfer happens over card network rails instead of ACH, funds are available to spend immediately, without waiting for a batch settlement cycle. However, creating a transfer and fulfilling it are two separate, asynchronous steps. Marqeta accepts a valid request immediately, then completes fulfillment in the background. A successful request means Marqeta accepted the transfer, not that funds have already moved. Track the outcome of a transfer with webhooks or by retrieving the transfer.

​

Use cases

Instant Card Transfers supports several money movement scenarios:

• Account funding: An account holder funds a new deposit account or card by pulling funds from an external card, instead of waiting on direct deposit or ACH.
• Cardholder funding (“me to me”): A cardholder tops up their Marqeta-issued card from a card of their own held elsewhere.
• Account-to-account (A2A) transfers: A cardholder sends funds from their Marqeta-issued card to their own external card.
• Business-to-consumer (B2C) disbursements: A Marqeta customer’s program disburses funds, such as gig-economy wages, insurance payouts, or government benefits, directly to a consumer’s external card.
• Business-to-business (B2B) transfers: A Marqeta customer sends funds to a commercial external card. Instant Card Transfers supports consumer, commercial, and B2B cards without differentiation, as long as the destination card passes validity checks for account funding transactions (AFT) and original credit transactions (OCT).

​

Transfer types

Every transfer you create has a transfer_type that determines the direction funds move:

• CARD_PULL: Pulls funds from an external card to a Marqeta-issued card or account.
• CARD_PUSH: Pushes funds from a Marqeta-issued card or account to an external card.
• CARD_DISBURSEMENT: Pushes funds to an external card with no associated Marqeta source account, such as a one-time payout.

​

Adding an external card

Before you can create a transfer, the external card involved must exist as an externalcard resource on the Marqeta platform. Send a POST request to /v3/moneymovement/externalcards with the card’s primary account number (PAN), CVV2, expiration date, and billing details. You must collect this data using your own PCI-compliant user interface. The billing details you supply must include either the external cardholder’s first and last name, or a business name, depending on whether the external account holder is a person or a business. See Add external card for sample request and response bodies covering both cases. If you already know which Marqeta user or business the external card belongs to, link it at add time by supplying user_token or business_token. This way, you can omit the corresponding token later when you create a transfer, as described in Creating a transfer. If you require a card to support push or pull transfers before you add it, set require_push_funds_eligibility or require_pull_funds_eligibility to true; the request fails if the card is not eligible. See Handling ineligible cards and failed requests.

​

Managing external cards

​

Listing a customer’s external cards

Send a GET request to /v3/moneymovement/externalcards/accountholders/{account_holder_token} to retrieve every external card associated with a user or business. Use the count and start_index query parameters to page through the results. See List external cards for the complete field reference.

​

Retrieving a single external card

Send a GET request to /v3/moneymovement/externalcards/{token} to retrieve a specific external card by its token. See Retrieve external card.

​

Checking a card’s status and eligibility

An external card’s status is ACTIVE, SUSPENDED, or TERMINATED. Its is_eligible_for_pull, is_eligible_for_push, and is_eligible_for_disbursement flags indicate which transfer_type values will succeed for that card. Check these values (returned when you add, list, or retrieve an external card) before creating a transfer, rather than relying on the transfer request to fail.

​

Suspending or terminating an external card

Send a PATCH request to /v3/moneymovement/externalcards/{token} with status set to SUSPENDED or TERMINATED, for example if the account holder removes the card or it becomes invalid. You can also reactivate a suspended card by setting its status back to ACTIVE. See Update external card.

​

Creating a transfer

Send a POST request to /v3/moneymovement/transfers with the transfer_type, the card_token of the external card, the amount, and the currency. Depending on the transfer type, you can optionally identify the Marqeta-side account holder using a user or business token, but only if you didn’t already link the external card to that user or business when you added it:

• For a CARD_PUSH transfer, use source_user_token or source_business_token, not both.
• For a CARD_PULL transfer, use destination_user_token or destination_business_token, not both.

CARD_DISBURSEMENT transfers don’t accept a source or destination token. See Create transfer for sample request bodies covering each combination.

​

Matching a use case to a transfer type

Several of the use cases described earlier use the same transfer_type. The difference between them is where in your flow you call the endpoint, not anything in the request itself:

​

Tracking fulfillment status

A successful POST request to /v3/moneymovement/transfers returns the transfer with status set to PENDING. This means the request passed validation and was accepted for processing. The funds haven’t moved yet. Marqeta then fulfills the transfer in the background. When fulfillment finishes, the transfer moves to a final status:

• COMPLETE: Funds moved successfully.
• REJECTED: Fulfillment failed, for example because the external card was declined. No funds moved.

A transfer can later move to CHARGEBACK if a dispute is raised after completion. To learn the outcome of a transfer, use one of these approaches:

• Webhooks (recommended): Subscribe to instantcardtransfertransition events, as described in Webhooks.
• Polling: Send a GET request to /v3/moneymovement/transfers/{token} and check status. Use this as a fallback, for example to reconcile after a missed webhook.

Don’t treat a PENDING transfer as successful. Wait for the transfer to reach COMPLETE before you credit the account holder or release goods or services. Pending transfers count toward the 24-hour rolling limit described in Velocity controls.

​

Viewing a transfer

​

Listing transfers for an account holder

Send a GET request to /v3/moneymovement/transfers/accountholders/{account_holder_token} to retrieve a paginated list of transfers for a user or business. Use the count and start_index query parameters to page through the results. See List transfers for an account holder.

​

Retrieving a single transfer

Send a GET request to /v3/moneymovement/transfers/{token} to retrieve a specific transfer by its token. See Retrieve transfer. A transfer’s status field defines the values PENDING, COMPLETE, REJECTED, and CHARGEBACK, matching the states a transfer moves through during fulfillment.

​

Handling ineligible cards and failed requests

A request can fail for a few different reasons:

• If you set require_push_funds_eligibility or require_pull_funds_eligibility to true when adding an external card, the request fails if the card doesn’t meet that requirement.
• If you create a transfer using a transfer_type the card isn’t eligible for, the request fails. Check the card’s is_eligible_for_pull, is_eligible_for_push, and is_eligible_for_disbursement flags first, as described in Checking a card’s status and eligibility.
• If you retrieve an external card or transfer with a token that doesn’t exist, the request returns a 404 response.

For the full list of Core API error codes, see Errors.

​

Velocity controls

Instant Card Transfers currently enforces two velocity controls, configured per program:

• A per-transaction amount limit.
• A 24-hour rolling daily amount limit, calculated per account holder from completed and pending transfers.

There’s currently no monthly transaction-count limit. If a program doesn’t configure these limits during onboarding, fallback default limits apply: $10,000 per transaction and $50,000 per rolling 24 hours.

​

Webhooks

Instant Card Transfers uses the same webhook subscription model available across the Marqeta platform. Subscribe to instantcardtransfertransition events to receive a notification as a transfer moves through fulfillment, such as when it completes, is rejected, or is charged back. For more information, see Instant card transfer transition events, About Webhooks, and the Webhooks API reference page.

​

Related content

• External Cards: add, list, retrieve, and update external cards.
• Transfers: create, list, and retrieve transfers.
• Money Movement Overview: how money moves through the Marqeta platform for standard card transactions.