/
10 minute read
May 3, 2022

Push-to-Card Payments (Beta)

The /pushtocards endpoint enables you to create a Push-to-Card payment card and disburse funds to it.

Note
This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.

A Push-to-Card payment card represents an external (non-Marqeta) card to which you want to disburse funds. You must add the details of this payment card to the Marqeta platform before disbursing funds.

A disbursement draws funds from your Push-to-Card funding reserve balance and sends (or "pushes") the funds to the specified payment card. Each disbursement requires an existing Push-to-Card payment card. A disbursement is not linked to any purchase. This type of disbursement is also known as an original credit transaction (OCT).

You can receive information about Push-to-Card disbursements as they occur by configuring webhooks such as pushtocard.debit and pushtocard.reversal. Learn about configuring webhooks in the Webhooks Overview guide. See the transaction events for which you can set up webhooks in the Event Types API reference page.

Note
Marqeta-issued cards and Push-to-Card payment cards are not interchangeable. Marqeta-issued cards are represented by the card object and enable users to make payments. Push-to-Card payment cards are represented by the paymentcard object and can only receive funds disbursed using the /pushtocards endpoint.

Create Push-to-Card payment card

Action: POST
Endpoint: /pushtocards/paymentcard

Creates a Push-to-Card payment card. A payment card represents a non-Marqeta card to which you can disburse funds. Each payment card must be associated with an existing user token.

Body field details
Fields Description

token

string
Optional

The unique identifier of the payment card.

If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

user_token

string
Required

The payment cardholder’s user token.

Allowable Values:

Existing user token.

To obtain a user token, send a GET request to the /users endpoint.

name_on_card

string
Required

The payment cardholder’s name as it appears on the card.

Allowable Values:

50 char max

pan

string
Required

The payment card’s primary account number.

Allowable Values:

19 char max

cvv

string
Required

The three-digit card verification value (CVV2) included on the back of the payment card.

Allowable Values:

3 char max

exp_date

string
Required

The payment card’s expiration date.

Allowable Values:

mmyy

address_1

string
Required

The payment cardholder’s billing address.

Allowable Values:

255 char max

address_2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Required

City of the payment cardholder’s billing address.

Allowable Values:

40 char max

state

string
Required

State of the payment cardholder’s billing address.

Allowable Values:

2 char max

postal_code

string
Required

ZIP or postal code of the payment cardholder’s billing address.

Allowable Values:

10 char max

country

string
Required

Country of the payment cardholder’s billing address, expressed as an ISO 3166 code. For example, the numeric code for the United States is 840, the alpha-2 code is US, and the alpha-3 code is USA.

If you pass the alpha-2 code, the alpha-3 code will be returned in the response.

The ISO maintains the full list of ISO 3166 country codes.

Allowable Values:

3 char max

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List Push-to-Card payment cards

Action: GET
Endpoint: /pushtocards/paymentcard

Retrieves a list of the existing Push-to-Card payment cards associated with a specific user.

Query parameters
Fields Description

user_token

string
Required

Identifies the user whose payment cards you want to list.

Allowable Values:

Existing user token.

To obtain a user token, send a GET request to /users.

Response body details
Fields Description

token

string
Returned

The unique identifier of the payment card.

Allowable Values:

36 char max

user_token

string
Returned

The payment cardholder’s user token.

Allowable Values:

Existing user token.

name_on_card

string
Returned

The payment cardholder’s name as it appears on the card.

Allowable Values:

50 char max

address_1

string
Returned

The payment cardholder’s street (billing) address.

Allowable Values:

255 char max

address_2

string
Returned

Additional address information.

Allowable Values:

255 char max

city

string
Returned

City of the payment cardholder’s billing address.

Allowable Values:

40 char max

state

string
Returned

State of the payment cardholder’s billing address.

Allowable Values:

2 char max

postal_code

string
Returned

ZIP or postal code of the payment cardholder’s billing address.

Allowable Values:

10 char max

country

string
Returned

Country of the payment cardholder’s billing address, expressed as an ISO 3166 code. For example, the numeric code for the United States is 840, the alpha-2 code is US, and the alpha-3 code is USA.

If you passed the alpha-2 code, the alpha-3 code is returned in the response.

Allowable Values:

3 char max

last_four

string
Returned

The last four digits of the payment card number.

Allowable Values:

4 char max

fast_fund_transfer_eligible

boolean
Returned

Indicates whether the external payment card issuer supports funding within 30 minutes for this payment card.

You must set this flag to true for a card to be eligible to receive Push-to-Card payments.

Allowable Values:

true, false

gambling_fund_transfer_eligible

boolean
Returned

Indicates whether the external payment card issuer supports gambling-related funding for this card.

Allowable Values:

true, false

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve Push-to-Card payment card

Action: GET
Endpoint: /pushtocards/paymentcard/{token}

Retrieves details about a specific Push-to-Card payment card.

URL path parameters
Fields Description

token

string
Required

Identifies the payment card to retrieve.

Allowable Values:

Existing payment card.

To obtain a paymentcard token, send a GET request to /pushtocards/paymentcard.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Create Push-to-Card disbursement

Action: POST
Endpoint: /pushtocards/disburse

Creates a Push-to-Card disbursement. A Push-to-Card disbursement represents an original credit transaction (OCT), which enables you to draw funds from your Push-to-Card funding reserve balance and send them to an external, non-Marqeta payment card.

Body field details
Fields Description

token

string
Optional

The unique identifier of the disbursement.

If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

currency_code

string
Required

The three-digit ISO 4217 currency code for the disbursement.

Allowable Values:

3 char max

amount

decimal
Required

The amount of the disbursement.

The maximum amount that you can disburse is determined by your program and/or the recipient financial institution.

Allowable Values:

Format: 0.00 or 0 (including the minor units of currency is optional)

payment_instrument_token

string
Required

The token of the Push-to-Card payment card.

Allowable Values:

Existing Push-to-Card payment card token.

tags

string
Optional

An arbitrary identifier.

Allowable Values:

255 char max

memo

string
Optional

A message describing the disbursement.

Allowable Values:

255 char max

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List Push-to-Card disbursements

Action: GET
Endpoint: /pushtocards/disburse

Retrieves a list of all the disbursements made to Push-to-Card payment cards.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve Push-to-Card disbursement

Action: GET
Endpoint: /pushtocards/disburse/{token}

Retrieves the details of a specific Push-to-Card disbursement.

URL path parameters
Fields Description

token

string
Required

Identifies the disbursement to retrieve.

Allowable Values:

Existing disbursement token.

To obtain a disbursement token, send a GET request to /pushtocards/disburse.

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter