Push-to-Card Payments

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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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"
}

Getting Started

Card Issuing

Card Processing

Accounts & Money Movement

Risk & Fraud

UX Toolkit

Push-to-Card Payments

Create Push-to-Card payment card

Body field details

Sample request body

Sample response body

List Push-to-Card payment cards

Query parameters

Response body details

Sample response body

Retrieve Push-to-Card payment card

URL path parameters

Sample response body

Create Push-to-Card disbursement

Body field details

Sample request body

Sample response body

List Push-to-Card disbursements

Sample response body

Retrieve Push-to-Card disbursement

URL path parameters

Sample response body

​Create Push-to-Card payment card

​Body field details

​Sample request body

​Sample response body

​List Push-to-Card payment cards

​Query parameters

​Response body details

​Sample response body

​Retrieve Push-to-Card payment card

​URL path parameters

​Sample response body

​Create Push-to-Card disbursement

​Body field details

​Sample request body

​Sample response body

​List Push-to-Card disbursements

​Sample response body

​Retrieve Push-to-Card disbursement

​URL path parameters

​Sample response body

Create Push-to-Card payment card

Body field details

Sample request body

Sample response body

List Push-to-Card payment cards

Query parameters

Response body details

Sample response body

Retrieve Push-to-Card payment card

URL path parameters

Sample response body

Create Push-to-Card disbursement

Body field details

Sample request body

Sample response body

List Push-to-Card disbursements

Sample response body

Retrieve Push-to-Card disbursement

URL path parameters

Sample response body