Skip to main content
Hidden
Note
This feature is currently in limited-availability alpha and subject to change. To learn more about the alpha program for this feature, contact your Marqeta representative.
Payee endpoints.

​
Get Payees for User

Action: GET
Endpoint: /users/{user_token}/payees Get a list of the linked payees associated with the user.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user resource.

Allowable Values:

36 char max

​
URL query parameters

FieldsDescription
name

string

Optional		Name of the payee to get.

Allowable Values:
page_size

integer

Optional		Number of results to display per page.

Allowable Values:

1 min
page_number

integer

Optional		Current page number of the returned results.

Allowable Values:

1 min

​
Response body

FieldsDescription
data

array of objects

Conditionally returned		One or more payment objects.

Allowable Values:
data[].biller

object

Conditionally returned		Biller linked to a payee or payment.

Allowable Values:
data[].biller.biller_token

string

Conditionally returned		Unique identifier of the biller resource.

Allowable Values:

2–36 chars
data[].biller.name

string

Conditionally returned		Name of the biller.

Allowable Values:

2–124 chars
data[].biller.logo

string

Conditionally returned		Logo of the biller.

Allowable Values:

255 char max
data[].biller.logo_type

string

Conditionally returned		Specifies the type of string for the value returned in the logo field.

Allowable Values:

URL, BINARY
data[].biller.address

object

Conditionally returned		The address of the biller.

Allowable Values:
data[].biller.address.address1

string

Conditionally returned		Street address of the biller.

Allowable Values:

36 char max
data[].biller.address.address2

string

Conditionally returned		Additional address information.

Allowable Values:

36 char max
data[].biller.address.city

string

Conditionally returned		City of the biller.

Allowable Values:

36 char max
data[].biller.address.country

string

Conditionally returned		Country of the biller.

Allowable Values:

40 char max
data[].biller.address.zip_code

string

Conditionally returned		United States ZIP code of the address.

Allowable Values:

20 char max
data[].biller.address.state

string

Conditionally returned		State of the biller.

Allowable Values:

36 char max
data[].biller.address.address_token

string

Conditionally returned		Unique identifier of the address resource.

Allowable Values:

36 char max
data[].user_token

string

Conditionally returned		The user associated with the payee

Allowable Values:

36 char max
data[].nickname

string

Conditionally returned		Nickname provided by user

Allowable Values:

36 char max
data[].payee_token

int64

Conditionally returned		The token of the linked payee

Allowable Values:

Existing payee token
data[].payee_name

string

Conditionally returned		Payee Name

Allowable Values:

36 char max
data[].account_number

string

Conditionally returned		User’s payee account number.

Allowable Values:

36 char max
data[].status

string

Conditionally returned		Status

Allowable Values:

ACTIVE, INACTIVE, DELETED
data[].payment_options

object

Conditionally returned		Contains list of payment options for associated Payee

Allowable Values:
data[].payment_options.card_options

array of objects

Conditionally returned		The list of cards and if convenience fee is applicable

Allowable Values:
data[].payment_options.card_options[].card_type

string

Conditionally returned		card_type

Allowable Values:

MASTERCARD_DEBIT, VISA_DEBIT
data[].payment_options.card_options[].has_convenience_fee

boolean

Conditionally returned		boolean value indicating if a convenience fee applies for the corresponding card type

Allowable Values:
data[].created_time

datetime

Conditionally returned		The time when payee was created.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
data[].last_modified_time

datetime

Conditionally returned		The time when payee was most recently modified.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
count

integer

Conditionally returned		Number of payee resources retrieved.

Allowable Values:

0 min
page_size

integer

Conditionally returned		Number of results to display per page.

Allowable Values:

1 min
page_number

integer

Conditionally returned		The current page number being returned of the results.

Allowable Values:

1 min
has_more

boolean

Conditionally returned		A value of true indicates that more unreturned resources exist.

Allowable Values:

​
Sample response body

JSON
{
  "data": [
    {
      "biller": {
        "biller_token": "a35Bcdi598sb=",
        "name": "Marqeta",
        "logo": "https://images.ctfassets.net/wqi8u1luxsv0/logo.svg/8559a40e8a503b55eeec4852e60efd49/logo.svg",
        "logo_type": "URL",
        "address": {
          "address1": "180 Grand Ave",
          "city": "Oakland",
          "country": "USA",
          "zip_code": "94612",
          "state": "CA",
          "address_token": "a35Bcdi598sb="
        }
      },
      "user_token": "user-token",
      "nickname": "MQ",
      "payee_token": "payee-token",
      "payee_name": "Marqeta",
      "account_number": "12345678",
      "status": "ACTIVE",
      "created_time": "2019-08-24T14:15:22Z",
      "last_modified_time": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 1,
  "page_size": 10,
  "page_number": 1,
  "has_more": false
}

​
Link Payee to User

Action: POST
Endpoint: /users/{user_token}/payees Link a new payee to a user.

​
URL path parameters

FieldsDescription
user_token

string

Required		User token

Allowable Values:

36 char max

​
Request body

The request object for linking a user and payee
FieldsDescription
biller_address_token

string

Optional		Unique identifier of the biller’s address.

Allowable Values:

Existing address token
biller_token

string

Required		Unique identifier of the biller resource.

Allowable Values:

36 char max
nickname

string

Optional		Descriptive name for the account.

Allowable Values:

36 char max
account_number

string

Required		The account number to be linked.

Allowable Values:

Existing account number

​
Sample request body

JSON
{
  "biller_address_token": "a35Bcdi598sb=",
  "biller_token": "a35Bcdi598sb=",
  "nickname": "MQ",
  "account_number": "12345678"
}

​
Response body

FieldsDescription
biller

object

Conditionally returned		Biller linked to a payee or payment.

Allowable Values:
biller.biller_token

string

Conditionally returned		Unique identifier of the biller resource.

Allowable Values:

2–36 chars
biller.name

string

Conditionally returned		Name of the biller.

Allowable Values:

2–124 chars
biller.logo

string

Conditionally returned		Logo of the biller.

Allowable Values:

255 char max
biller.logo_type

string

Conditionally returned		Specifies the type of string for the value returned in the logo field.

Allowable Values:

URL, BINARY
biller.address

object

Conditionally returned		The address of the biller.

Allowable Values:
biller.address.address1

string

Conditionally returned		Street address of the biller.

Allowable Values:

36 char max
biller.address.address2

string

Conditionally returned		Additional address information.

Allowable Values:

36 char max
biller.address.city

string

Conditionally returned		City of the biller.

Allowable Values:

36 char max
biller.address.country

string

Conditionally returned		Country of the biller.

Allowable Values:

40 char max
biller.address.zip_code

string

Conditionally returned		United States ZIP code of the address.

Allowable Values:

20 char max
biller.address.state

string

Conditionally returned		State of the biller.

Allowable Values:

36 char max
biller.address.address_token

string

Conditionally returned		Unique identifier of the address resource.

Allowable Values:

36 char max
user_token

string

Conditionally returned		The user associated with the payee

Allowable Values:

36 char max
nickname

string

Conditionally returned		Nickname provided by user

Allowable Values:

36 char max
payee_token

int64

Conditionally returned		The token of the linked payee

Allowable Values:

Existing payee token
payee_name

string

Conditionally returned		Payee Name

Allowable Values:

36 char max
account_number

string

Conditionally returned		User’s payee account number.

Allowable Values:

36 char max
status

string

Conditionally returned		Status

Allowable Values:

ACTIVE, INACTIVE, DELETED
payment_options

object

Conditionally returned		Contains list of payment options for associated Payee

Allowable Values:
payment_options.card_options

array of objects

Conditionally returned		The list of cards and if convenience fee is applicable

Allowable Values:
payment_options.card_options[].card_type

string

Conditionally returned		card_type

Allowable Values:

MASTERCARD_DEBIT, VISA_DEBIT
payment_options.card_options[].has_convenience_fee

boolean

Conditionally returned		boolean value indicating if a convenience fee applies for the corresponding card type

Allowable Values:
created_time

datetime

Conditionally returned		The time when payee was created.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		The time when payee was most recently modified.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "biller": {
    "biller_token": "a35Bcdi598sb=",
    "name": "Marqeta",
    "logo": "https://images.ctfassets.net/wqi8u1luxsv0/logo.svg/8559a40e8a503b55eeec4852e60efd49/logo.svg",
    "logo_type": "URL",
    "address": {
      "address1": "180 Grand Ave",
      "city": "Oakland",
      "country": "USA",
      "zip_code": "94612",
      "state": "CA",
      "address_token": "a35Bcdi598sb="
    }
  },
  "user_token": "user-token",
  "nickname": "MQ",
  "payee_token": "payee-token",
  "payee_name": "Marqeta",
  "account_number": "12345678",
  "status": "ACTIVE",
  "payment_options": {
    "card_options": [
      {
        "card_type": "VISA_DEBIT",
        "has_convenience_fee": false
      },
      {
        "card_type": "MASTERCARD_DEBIT",
        "has_convenience_fee": false
      }
    ]
  },
  "created_time": "2019-08-24T14:15:22Z",
  "last_modified_time": "2019-08-24T14:15:22Z"
}

​
Delete Payee for User

Action: DELETE
Endpoint: /users/{user_token}/payees/{payee_token} Delete a payee that is associated with a user.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user resource.

Allowable Values:

36 char max
payee_token

string

Required		The token of the linked payee.

Allowable Values:

​
URL query parameters

FieldsDescription
deletePendingPayments

boolean

Optional		Delete Pending Payments?

Allowable Values:

​
Response body

FieldsDescription
message

string

Conditionally returned		The message for delete payee action

Allowable Values:

​
Sample response body

JSON
{
  "message": "Payee successfully deleted"
}

​
Get Payee for User

Action: GET
Endpoint: /users/{user_token}/payees/{payee_token} Get a linked payee associated with the user.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user resource.

Allowable Values:

36 char max
payee_token

string

Required		The token of the linked payee.

Allowable Values:

​
Response body

FieldsDescription
biller

object

Conditionally returned		Biller linked to a payee or payment.

Allowable Values:
biller.biller_token

string

Conditionally returned		Unique identifier of the biller resource.

Allowable Values:

2–36 chars
biller.name

string

Conditionally returned		Name of the biller.

Allowable Values:

2–124 chars
biller.logo

string

Conditionally returned		Logo of the biller.

Allowable Values:

255 char max
biller.logo_type

string

Conditionally returned		Specifies the type of string for the value returned in the logo field.

Allowable Values:

URL, BINARY
biller.address

object

Conditionally returned		The address of the biller.

Allowable Values:
biller.address.address1

string

Conditionally returned		Street address of the biller.

Allowable Values:

36 char max
biller.address.address2

string

Conditionally returned		Additional address information.

Allowable Values:

36 char max
biller.address.city

string

Conditionally returned		City of the biller.

Allowable Values:

36 char max
biller.address.country

string

Conditionally returned		Country of the biller.

Allowable Values:

40 char max
biller.address.zip_code

string

Conditionally returned		United States ZIP code of the address.

Allowable Values:

20 char max
biller.address.state

string

Conditionally returned		State of the biller.

Allowable Values:

36 char max
biller.address.address_token

string

Conditionally returned		Unique identifier of the address resource.

Allowable Values:

36 char max
user_token

string

Conditionally returned		The user associated with the payee

Allowable Values:

36 char max
nickname

string

Conditionally returned		Nickname provided by user

Allowable Values:

36 char max
payee_token

int64

Conditionally returned		The token of the linked payee

Allowable Values:

Existing payee token
payee_name

string

Conditionally returned		Payee Name

Allowable Values:

36 char max
account_number

string

Conditionally returned		User’s payee account number.

Allowable Values:

36 char max
status

string

Conditionally returned		Status

Allowable Values:

ACTIVE, INACTIVE, DELETED
payment_options

object

Conditionally returned		Contains list of payment options for associated Payee

Allowable Values:
payment_options.card_options

array of objects

Conditionally returned		The list of cards and if convenience fee is applicable

Allowable Values:
payment_options.card_options[].card_type

string

Conditionally returned		card_type

Allowable Values:

MASTERCARD_DEBIT, VISA_DEBIT
payment_options.card_options[].has_convenience_fee

boolean

Conditionally returned		boolean value indicating if a convenience fee applies for the corresponding card type

Allowable Values:
created_time

datetime

Conditionally returned		The time when payee was created.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		The time when payee was most recently modified.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "biller": {
    "biller_token": "a35Bcdi598sb=",
    "name": "Marqeta",
    "logo": "https://images.ctfassets.net/wqi8u1luxsv0/logo.svg/8559a40e8a503b55eeec4852e60efd49/logo.svg",
    "logo_type": "URL",
    "address": {
      "address1": "180 Grand Ave",
      "city": "Oakland",
      "country": "USA",
      "zip_code": "94612",
      "state": "CA",
      "address_token": "a35Bcdi598sb="
    }
  },
  "user_token": "user-token",
  "nickname": "MQ",
  "payee_token": "payee-token",
  "payee_name": "Marqeta",
  "account_number": "12345678",
  "status": "ACTIVE",
  "payment_options": {
    "card_options": [
      {
        "card_type": "VISA_DEBIT",
        "has_convenience_fee": false
      },
      {
        "card_type": "MASTERCARD_DEBIT",
        "has_convenience_fee": false
      }
    ]
  },
  "created_time": "2019-08-24T14:15:22Z",
  "last_modified_time": "2019-08-24T14:15:22Z"
}

Related topics

PaymentsBill PaymentsPayment SchedulesIntroduction to Bill PayBill Pay Users