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.
Bill payment endpoints.

​
Get Payments

Action: GET
Endpoint: /users/{user_token}/payments Get a list of payments made by 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
payee_token

string

Optional		Filter by payments made to a specific payee.

Allowable Values:

Existing user resource token.
page_size

integer

Optional		Number of results to display per page.

Allowable Values:

1–50
page_number

integer

Optional		Current page number of the returned results.

Allowable Values:

1 min
start_date

date

Optional		Start of the date range during which payments were created.

Allowable Values:

yyyy-MM-dd Defaults to 60 days prior to current date
end_date

date

Optional		End of the date range during which payments were created.

Allowable Values:

yyyy-MM-dd

​
Response body

FieldsDescription
data

array of objects

Conditionally returned		One or more payment objects.

Allowable Values:
data[].payment_token

string

Conditionally returned		Unique identifier of the payment.

Allowable Values:

36 char max
data[].user_token

string

Conditionally returned		Unique identifier of the user making the request.

Allowable Values:

Existing user resource token.
data[].payee_token

string

Conditionally returned		Unique identifier of the party receiving payment.

Allowable Values:

Existing payee resource token
data[].card_token

string

Conditionally returned		Unique identifier of the card resource.

Allowable Values:

Existing card token
data[].amount

decimal

Conditionally returned		Payment amount in USD.

Allowable Values:

0.01 min
data[].convenience_fee

decimal

Conditionally returned		Convenience fee amount, as set by the payment recipient.

Allowable Values:

0 min
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[].processing_date

date

Conditionally returned		Processing date of payment.

Allowable Values:

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

date

Conditionally returned		Delivery date of payment.

Allowable Values:

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

datetime

Conditionally returned		Date and time when the payment resource was created, in UTC.

Allowable Values:

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

datetime

Conditionally returned		Date and time when the payment resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
count

integer

Conditionally returned		Number of payment 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		Current page number 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": [
    {
      "payment_token": "payment-token",
      "user_token": "user-token",
      "payee_token": "payee-token",
      "card_token": "card-token",
      "amount": 25,
      "convenience_fee": 1,
      "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="
        }
      },
      "processing_date": "2019-08-24T00:00:00Z",
      "delivery_date": "2019-08-24T00:00:00Z",
      "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
}

​
Make a Payment to a Payee

Action: POST
Endpoint: /users/{user_token}/payments Post a payment to a payee that is linked to a user’s account.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user resource.

Allowable Values:

36 char max

​
Request body

FieldsDescription
user_token

string

Required		Unique identifier of the user making the request.

Allowable Values:

Existing user resource token.
payee_token

string

Required		Unique identifier of the party receiving payment.

Allowable Values:

Existing payee resource token
card_token

string

Required		Unique identifier of the card resource.

Allowable Values:

Existing card token
amount

decimal

Required		Payment amount in USD.

Allowable Values:

0.01 min

​
Sample request body

JSON
{
  "user_token": "user-token",
  "payee_token": "payee-token",
  "card_token": "card-token",
  "amount": 25
}

​
Response body

FieldsDescription
payment_token

string

Conditionally returned		Unique identifier of the payment.

Allowable Values:

36 char max
user_token

string

Conditionally returned		Unique identifier of the user making the request.

Allowable Values:

Existing user resource token.
payee_token

string

Conditionally returned		Unique identifier of the party receiving payment.

Allowable Values:

Existing payee resource token
card_token

string

Conditionally returned		Unique identifier of the card resource.

Allowable Values:

Existing card token
amount

decimal

Conditionally returned		Payment amount in USD.

Allowable Values:

0.01 min
convenience_fee

decimal

Conditionally returned		Convenience fee amount, as set by the payment recipient.

Allowable Values:

0 min
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
processing_date

date

Conditionally returned		Processing date of payment.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
delivery_date

date

Conditionally returned		Delivery date of payment.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
created_time

datetime

Conditionally returned		Date and time when the payment resource was created, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		Date and time when the payment resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "payment_token": "payment-token",
  "user_token": "user-token",
  "payee_token": "payee-token",
  "card_token": "card-token",
  "amount": 25,
  "convenience_fee": 1,
  "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="
    }
  },
  "processing_date": "2019-08-24T00:00:00Z",
  "delivery_date": "2019-08-24T00:00:00Z",
  "created_dime": "2019-08-24T14:15:22Z",
  "last_modified_time": "2019-08-24T14:15:22Z"
}

​
Get Payments

Action: GET
Endpoint: /users/{user_token}/payments/{payment_token} Get a payment made by the user.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user resource.

Allowable Values:

36 char max
payment_token

string

Required		The token of the payment to get.

Allowable Values:

​
Response body

FieldsDescription
payment_token

string

Conditionally returned		Unique identifier of the payment.

Allowable Values:

36 char max
user_token

string

Conditionally returned		Unique identifier of the user making the request.

Allowable Values:

Existing user resource token.
payee_token

string

Conditionally returned		Unique identifier of the party receiving payment.

Allowable Values:

Existing payee resource token
card_token

string

Conditionally returned		Unique identifier of the card resource.

Allowable Values:

Existing card token
amount

decimal

Conditionally returned		Payment amount in USD.

Allowable Values:

0.01 min
convenience_fee

decimal

Conditionally returned		Convenience fee amount, as set by the payment recipient.

Allowable Values:

0 min
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
processing_date

date

Conditionally returned		Processing date of payment.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
delivery_date

date

Conditionally returned		Delivery date of payment.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
created_time

datetime

Conditionally returned		Date and time when the payment resource was created, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		Date and time when the payment resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "payment_token": "payment-token",
  "user_token": "user-token",
  "payee_token": "payee-token",
  "card_token": "card-token",
  "amount": 25,
  "convenience_fee": 1,
  "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="
    }
  },
  "processing_date": "2019-08-24T00:00:00Z",
  "delivery_date": "2019-08-24T00:00:00Z",
  "created_time": "2019-08-24T14:15:22Z",
  "last_modified_time": "2019-08-24T14:15:22Z"
}

Related topics

Introduction to Bill PayPayment SchedulesPaymentsBill Pay UsersPush-to-Card Payments