Note
This feature is currently in beta and subject to change. To learn more about the Beta program for this feature, contact your Marqeta representative.
This feature is currently in beta and subject to change. To learn more about the Beta program for this feature, contact your Marqeta representative.
Add external card
Action:POSTEndpoint:
/moneymovement/externalcards
Adds a new external card for use in payment transactions.
Request body
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the external card. Allowable Values: 36 char max |
| pan string Required | Primary account number (PAN) of the external card. Allowable Values: 16 char max |
| cvv string Required | Card verification value (CVV2) of the external card. Allowable Values: Valid CVV2 |
| expiration string Required | Expiration date of the external card. Allowable Values: Format: MMyy |
| postal_code string Required | Postal code of the external cardholder’s address. Allowable Values: 20 char max |
| birth_date string Required | External cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
| require_push_funds_eligibility boolean Optional | A value of true indicates that the card must be eligible to push funds and the request will fail if it is ineligible.Allowable Values: true, false |
| require_pull_funds_eligibility boolean Optional | A value of true indicates that the card must be eligible to pull funds and the request will fail if it is ineligible.Allowable Values: true, false |
| non_marqeta_user_details object Optional | External cardholder details. Allowable Values: first_name, middle_name, last_name, address_1, address_2, city, country_subdivision, postal_code, country |
| non_marqeta_user_details.first_name string Optional | First name or given name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.middle_name string Optional | Middle name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.last_name string Optional | Last or family name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.address_1 string Optional | Street name and number of the external cardholder’s address. Allowable Values: 255 char max |
| non_marqeta_user_details.address_2 string Optional | Additional external cardholder address information. Allowable Values: 255 char max |
| non_marqeta_user_details.city string Optional | City of the external cardholder’s address. Allowable Values: 40 char max |
| non_marqeta_user_details.country_subdivision string Optional | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| non_marqeta_user_details.postal_code string Optional | Postal code of the external cardholder’s address. Allowable Values: 20 char max |
| non_marqeta_user_details.country string Optional | Country of the external cardholder’s address. Allowable Values: 3 char max |
| marqeta_user_details object Optional | Cardholder details for a Marqeta platform user. This field is required if the non_marqeta_user_details field is not supplied.Allowable Values: user_token |
| marqeta_user_details.user_token string Optional | Unique identifier of the Marqeta user resource.Send a GET request to /users to retrieve user tokens.Allowable Values: Existing user token |
Response body
| Fields | Description |
|---|---|
| token string Conditionally returned | Unique identifier of the external card. Allowable Values: 36 char max |
| expiration string Conditionally returned | Expiration date of the external card. Allowable Values: Format: mmYY |
| last_four string Conditionally returned | Last four digits of the primary account number (PAN) of the external card. Allowable Values: 4 char |
| issuing_bank string Conditionally returned | Issuing bank of the external card. Allowable Values: Bank name, as provided by the card network |
| network string Conditionally returned | Name of the payment card network. Allowable Values: 255 char max |
| status string Conditionally returned | Status of the external card, based on its expiration date. Allowable Values: ACTIVE, SUSPENDED |
| non_marqeta_user_details object Conditionally returned | External cardholder details. Allowable Values: first_name, middle_name, last_name, address_1, address_2, city, country_subdivision, postal_code, country |
| non_marqeta_user_details.first_name string Conditionally returned | First name or given name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.middle_name string Conditionally returned | Middle name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.last_name string Conditionally returned | Last or family name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.address_1 string Conditionally returned | Street name and number of the external cardholder’s address. Allowable Values: 255 char max |
| non_marqeta_user_details.address_2 string Conditionally returned | Additional external cardholder address information. Allowable Values: 255 char max |
| non_marqeta_user_details.city string Conditionally returned | City of the external cardholder’s address. Allowable Values: 40 char max |
| non_marqeta_user_details.country_subdivision string Conditionally returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| non_marqeta_user_details.postal_code string Conditionally returned | Postal code of the external cardholder’s address. Allowable Values: 20 char max |
| non_marqeta_user_details.country string Conditionally returned | Country of the external cardholder’s address. Allowable Values: 3 char max |
| marqeta_user_details object Conditionally returned | Cardholder details for a Marqeta platform user. Allowable Values: user_token |
| marqeta_user_details.user_token string Conditionally returned | Unique identifier of the Marqeta user resource.Allowable Values: Existing user token |
| is_eligible_for_pull boolean Conditionally returned | A value of true indicates that the card is eligible for pulling funds.Allowable Values: true, false |
| is_eligible_for_push boolean Conditionally returned | A value of true indicates that the card is eligible for pushing funds.Allowable Values: true, false |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Conditionally returned | Date and time when the resource was updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
List external cards
Action:GETEndpoint:
/moneymovement/externalcards
Retrieves a list of external cards.
URL query parameters
| Fields | Description |
|---|---|
| user_token string Optional | Unique identifier of the user for whom to retrieve a list of cards. Allowable Values: Valid user token |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| count integer Optional | Number of card resources to retrieve. Allowable Values: 1-10 Default value: 3 |
| sort_by string Optional | Field on which to sort. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending orderAllowable Values: created_time, -created_time, last_modified_time, -last_modified_time |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of external card resources to retrieve. Allowable Values: 1-10 |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist.Allowable Values: true, false |
| data array of objects Conditionally returned | Array of card objects. Allowable Values: Valid array of one or more card objects |
| data[].marqeta_user_details object Conditionally returned | Cardholder details for a Marqeta platform user. Allowable Values: user_token |
| data[].non_marqeta_user_details object Conditionally returned | External cardholder details. Allowable Values: first_name, middle_name, last_name, address_1, address_2, city, country_subdivision, postal_code, country |
| data[].token string Returned | Unique identifier of the external card. Allowable Values: Existing external card token |
| data[].expiration date Conditionally returned | Expiration date of the external card. Allowable Values: Format: mmYY |
| data[].last_four string Conditionally returned | Last four digits of the external card’s primary account number (PAN). Allowable Values: 4 char max |
| data[].network string Conditionally returned | Card network associated with the external card. Allowable Values: VISA, MASTERCARD |
| data[].issuing_bank string Conditionally returned | Issuing bank of the external card. Allowable Values: Bank name, as provided by the card network |
| data[].status string Conditionally returned | Status of the external card, based on its expiration date. Allowable Values: ACTIVE, SUSPENDED |
| data[].created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| data[].last_modified_time datetime Conditionally returned | Date and time when the resource was updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| data[].eligible_for_pull boolean Conditionally returned | A value of true indicates that the external card is eligible for pulling funds.Allowable Values: true, false |
| data[].eligible_for_push boolean Conditionally returned | A value of true indicates that the external card is eligible for pushing funds.Allowable Values: true, false |
Retrieve external card
Action:GETEndpoint:
/moneymovement/externalcards/{token}
Retrieve an external card using the specified external card token.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the external card, as returned by the POST /externalcards endpoint.Allowable Values: Valid external card token |
Response body
| Fields | Description |
|---|---|
| marqeta_user_details object Conditionally returned | Cardholder details for a Marqeta platform user. Allowable Values: user_token |
| marqeta_user_details.user_token string Conditionally returned | Unique identifier of the Marqeta user resource.Allowable Values: 36 char max |
| non_marqeta_user_details object Conditionally returned | External cardholder details. Allowable Values: first_name, middle_name, last_name, address_1, address_2, city, country_subdivision, postal_code, country |
| non_marqeta_user_details.first_name string Conditionally returned | First name or given name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.middle_name string Conditionally returned | Middle name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.last_name string Conditionally returned | Last or family name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.address_1 string Conditionally returned | Street name and number of the external cardholder’s address. Allowable Values: 255 char max |
| non_marqeta_user_details.address_2 string Conditionally returned | Additional external cardholder address information. Allowable Values: 255 char max |
| non_marqeta_user_details.city string Conditionally returned | City of the external cardholder’s address. Allowable Values: 40 char max |
| non_marqeta_user_details.country_subdivision string Conditionally returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| non_marqeta_user_details.postal_code string Conditionally returned | Postal code of the external cardholder’s address. Allowable Values: 20 char max |
| non_marqeta_user_details.country string Conditionally returned | Country of the external cardholder’s address. Allowable Values: 3 char max |
| token string Returned | Unique identifier of the external card. Allowable Values: 36 char max |
| expiration dateTime Conditionally returned | External card expiration date. Allowable Values: Format: mmYY |
| last_four string Conditionally returned | Last four digits of the external card’s primary account number (PAN). Allowable Values: 4 char max |
| network string Conditionally returned | Card network associated with the external card. Allowable Values: VISA, MASTERCARD |
| issuing_bank string Conditionally returned | Issuing bank of the external card. Allowable Values: Bank name, as provided by the card network |
| status string Conditionally returned | Status of the external card, based on its expiration date. Allowable Values: ACTIVE, SUSPENDED |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Conditionally returned | Date and time when the resource was updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| eligible_for_pull boolean Conditionally returned | A value of true indicates that the external card is eligible for pulling funds.Allowable Values: true, false |
| eligible_for_push boolean Conditionally returned | A value of true indicates that the external card is eligible for pushing funds.Allowable Values: true, false |
Delete external card
Action:PATCHEndpoint:
/moneymovement/externalcards/{token}
Delete an external debit or prepaid card from the user’s profile.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the external card, as returned by the POST /externalcards endpoint.Allowable Values: Valid external card token |
Request body
| Fields | Description |
|---|---|
| status string Required | Status to which to update the external card. Allowable Values: DELETED, SUSPENDED |
Response body
| Fields | Description |
|---|---|
| marqeta_user_details object Conditionally returned | Cardholder details for a Marqeta platform user. Allowable Values: user_token |
| marqeta_user_details.user_token string Conditionally returned | Unique identifier of the Marqeta user resource.Allowable Values: Existing user token |
| non_marqeta_user_details object Conditionally returned | External cardholder details. Allowable Values: first_name, middle_name, last_name, address_1, address_2, city, country_subdivision, postal_code, country |
| non_marqeta_user_details.first_name string Conditionally returned | First name or given name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.middle_name string Conditionally returned | Middle name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.last_name string Conditionally returned | Last or family name of the external cardholder. Allowable Values: 40 char max |
| non_marqeta_user_details.address_1 string Conditionally returned | Street name and number of the external cardholder’s address. Allowable Values: 255 char max |
| non_marqeta_user_details.address_2 string Conditionally returned | Additional external cardholder address information. Allowable Values: 255 char max |
| non_marqeta_user_details.city string Conditionally returned | City of the external cardholder’s address. Allowable Values: 40 char max |
| non_marqeta_user_details.country_subdivision string Conditionally returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| non_marqeta_user_details.postal_code string Conditionally returned | Postal code of the external cardholder’s address. Allowable Values: 20 char max |
| non_marqeta_user_details.country string Conditionally returned | Country of the external cardholder’s address. Allowable Values: 3 char max |
| token string Returned | Unique identifier of the external card. Allowable Values: 36 char max |
| expiration dateTime Conditionally returned | Expiration date of the external card. Allowable Values: Format: mmYY |
| last_four string Conditionally returned | Last four digits of the external card. Allowable Values: 4 char max |
| network string Conditionally returned | Card network associated with the external card. Allowable Values: VISA, MASTERCARD |
| issuing_bank string Conditionally returned | Issuing bank of the external card. Allowable Values: Bank name, as provided by the card network |
| status string Conditionally returned | Status of the external card, based on its expiration date. Allowable Values: ACTIVE, SUSPENDED |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Conditionally returned | Date and time when the resource was updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| eligible_for_pull boolean Conditionally returned | A value of true indicates that the external card is eligible for pulling funds.Allowable Values: true, false |
| eligible_for_push boolean Conditionally returned | A value of true indicates that the external card is eligible for pushing funds.Allowable Values: true, false |
Create transfer
Action:POSTEndpoint:
/moneymovement/transfers
Transfer funds to a recipient’s card.
Request body
| Fields | Description |
|---|---|
| amount decimal Required | Amount to transfer. Allowable Values: Any number between 0.01 and 1000000000 |
| currency string Required | Alpha-3 currency code. Allowable Values: Valid alpha-3 currency code |
| token string Optional | Unique identifier for the transfer to be created. Allowable Values: 36 char max |
| statement_descriptor string Optional | Description of the transaction, as it will appear on the recipient’s bank statement. Allowable Values: 22 char max |
| card_transfer object Optional | Card transfer details. This field is required if the card_disbursement field is not included.Allowable Values: source_card_token, destination_card_token |
| card_transfer.source_card_token string Required | Unique identifier of the card funding the transfer. Allowable Values: Existing card token |
| card_transfer.destination_card_token string Required | Unique identifier of the card receiving the transfer. Allowable Values: Existing card token |
| card_disbursement object Optional | Card disbursement details. This field is required if the card_transfer field is not included.Allowable Values: destination_card_token |
| card_disbursement.destination_card_token string Required | Unique identifier of the card receiving the disbursement. Allowable Values: 36 char max |
List transfers by user or card
Action:GETEndpoint:
/moneymovement/transfers
Returns a paginated list of transfers for a specific user or card.
URL query parameters
| Fields | Description |
|---|---|
| user_token string Optional | Unique identifier of the user for which to retrieve transfers. Allowable Values: Valid user token |
| card_token string Optional | Unique identifier of the card for which to retrieve transfers. Allowable Values: Valid card token |
| count integer Optional | Number of transfers to return. Allowable Values: 1-10 |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| sort_by string Optional | Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: created_time, -created_time, last_modified_time, -last_modified_time |
| start_date string Optional | Start date for the transfer query. Allowable Values: Format: yyyy-MM-dd |
| end_date string Optional | End date for the transfer query. Allowable Values: Format: yyyy-MM-dd |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of transfer resources to retrieve. Allowable Values: 1-10 |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist.Allowable Values: true, false |
| data array of objects Conditionally returned | Array of transfer objects. Allowable Values: Valid array of one or more transfer objects |
| data[].token string Conditionally returned | Unique identifier for the transfer. Allowable Values: Existing transfer token |
| data[].amount decimal Conditionally returned | Amount of the transfer. Allowable Values: Format: 0.00 |
| data[].currency string Conditionally returned | Alpha-3 currency code. Allowable Values: Valid alpha-3 currency code |
| data[].status string Conditionally returned | Processing state of the transaction. Allowable Values: COMPLETE |
| data[].card_transfer object Conditionally returned | Card transfer details. Allowable Values: source_card_token, destination_card_token |
| data[].statement_descriptor string Conditionally returned | Description of the transaction, as it will appear on the recipient’s bank statement. Allowable Values: 22 char max |
| data[].created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| data[].last_modified_time datetime Conditionally returned | Date and time when the resource was updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve transfer
Action:GETEndpoint:
/moneymovement/transfers/{token}
Retrieve a transfer using the specified transfer token.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Transfer token that was returned when the transfer was created. Allowable Values: Valid transfer token |
Response body
| Fields | Description |
|---|---|
| card_token string Conditionally returned | Card token obtained from the POST /moneymovement/externalcards endpoint above.Allowable Values: 36 char max |
| token string Conditionally returned | Unique identifier for the transfer to be created. Allowable Values: 36 char max |
| amount string Conditionally returned | Amount of the transfer. Allowable Values: Any number between 0.01 and 1000000000 |
| currency string Conditionally returned | Three-digit ISO 4217 currency code. Allowable Values: A valid three-digit ISO 4217 currency code |
| statement_descriptor string Conditionally returned | Description of the transaction, as it will appear on the recipient’s bank statement. Allowable Values: 22 char max |
| card_transfer object Conditionally returned | Card transfer details. Allowable Values: source_card_token, destination_card_token |
| card_transfer.source_card_token string Conditionally returned | Unique identifier of the card funding the transfer. Allowable Values: 36 char max |
| card_transfer.destination_card_token string Conditionally returned | Unique identifier of the card receiving the transfer. Allowable Values: 36 char max |
| status string Conditionally returned | Processing state of the transaction. Allowable Values: COMPLETE |
| created_time dateTime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time dateTime Conditionally returned | Date and time when the resource was updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |