Skip to main content
Hidden
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.
The /pushtocards endpoint enables you to create a Push-to-Card payment card and disburse funds to it. 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 About Webhooks 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

FieldsDescription
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
{
  "user_token": "myUser",
  "name_on_card": "John Smith",
  "pan": "1234123412341234",
  "cvv": "123",
  "exp_date": "0120",
  "address_1": "123 Main Street",
  "city": "Oakland",
  "state": "CA",
  "postal_code":  "94601",
  "country": "USA"
}

​
Sample response body

JSON
{
  "created_time": "2021-02-22T18:16:32Z",
  "last_modified_time": "2021-02-22T18:16:36Z",
  "address_1": "123 Main Street",
  "city": "Oakland",
  "state": "CA",
  "postal_code": "94601",
  "country": "USA",
  "last_four": "1234",
  "token": "8fdc41ee-95c5-4a06-83a3-3e6f2537b787",
  "fast_fund_transfer_eligible": true,
  "gambling_fund_transfer_eligible": false,
  "name_on_card": "John Smith"
}

​
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

FieldsDescription
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

FieldsDescription
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
{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "created_time": "2021-02-22T18:16:32Z",
      "last_modified_time": "2021-02-22T18:16:36Z",
      "address_1": "123 Main Street",
      "city": "Oakland",
      "state": "CA",
      "postal_code": "94601",
      "country": "USA",
      "last_four": "1234",
      "token": "8fdc41ee-95c5-4a06-83a3-3e6f2537b787",
      "fast_fund_transfer_eligible": true,
      "gambling_fund_transfer_eligible": false,
      "name_on_card": "John Smith"
    }
  ]
}

​
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

FieldsDescription
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
{
  "created_time": "2021-02-22T18:16:32Z",
  "last_modified_time": "2021-02-22T18:16:36Z",
  "address_1": "123 Main Street",
  "city": "Oakland",
  "state": "CA",
  "postal_code": "94601",
  "country": "USA",
  "last_four": "1234",
  "token": "8fdc41ee-95c5-4a06-83a3-3e6f2537b787",
  "fast_fund_transfer_eligible": true,
  "gambling_fund_transfer_eligible": false,
  "name_on_card": "John Smith"
}

​
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

FieldsDescription
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
{
  "currency_code": "840",
  "amount": 10.00,
  "payment_instrument_token": "8b2bz20d-7cdc-492b-81z4-77a295z1e471"
}

​
Sample response body

JSON
{
  "created_time": "2021-02-22T18:17:19Z",
  "last_modified_time": "2021-02-22T18:17:19Z",
  "token": "e50d56cb-9aeb-4a13-a6c4-ed1f089a5ea5",
  "currency_code": "USD",
  "amount": 10.00,
  "status": "success",
  "payment_instrument_token": "8b2bz20d-7cdc-492b-81z4-77a295z1e471"
}

​
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
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
   "data": [
    {
      "created_time": "2021-02-22T18:18:58Z",
      "last_modified_time": "2021-02-22T18:18:58Z",
      "token": "4fc83b87-816e-4f67-8819-3a22d912943c",
      "amount": 5.25,
      "status": "success",
      "payment_instrument_token": "8fdc41ee-95c5-4a06-83a3-3e6f2537b787"
    },
    {
      "created_time": "2021-02-22T18:17:19Z",
      "last_modified_time": "2021-02-22T18:17:19Z",
      "token": "e50d56cb-9aeb-4a13-a6c4-ed1f089a5ea5",
      "currency_code": "USD",
      "amount": 10.00,
      "status": "success",
      "payment_instrument_token": "8b2bz20d-7cdc-492b-81z4-77a295z1e471"
     }
  ]
}

​
Retrieve Push-to-Card disbursement

Action: GET
Endpoint: /pushtocards/disburse/{token} Retrieves the details of a specific Push-to-Card disbursement.

​
URL path parameters

FieldsDescription
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
{
  "created_time": "2021-02-22T18:17:19Z",
  "last_modified_time": "2021-02-22T18:17:19Z",
  "token": "e50d56cb-9aeb-4a13-a6c4-ed1f089a5ea5",
  "currency_code": "USD",
  "amount": 10.00,
  "status": "success",
  "payment_instrument_token": "8b2bz20d-7cdc-492b-81z4-77a295z1e471"
}

Related topics

Simulations 2.0 — Card TransactionsPayment Cards ConceptsBulk Card OrdersPayment SourcesDisputes (Mastercard)