Payment Schedules

Use the payment schedule endpoints to create and retrieve payment schedules and payment schedule transitions on a credit account. A payment schedule allows you to schedule a one-time or recurring payment on a credit account. For more on payments, see About Credit Account Payments. To receive webhook notifications when ACH payment transition events occur, see Credit account payment transition events in Event Types. Making a payment on a payment schedule triggers the creation of a journal entry belonging to the PAYMENT group. For more on payment journal entries, see Payments in the About Credit Account Journal Entries guide.

Create payment schedule

Action: POST
Endpoint: /credit/accounts/{account_token}/paymentschedules Create a new payment schedule, either one-time or recurring.

URL path parameters

Fields	Description
account_token string Required	Unique identifier of the credit account for which you want to create a payment schedule. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token

Request body

Fields	Description
token string Optional	Unique identifier of the payment schedule. Allowable Values: 36 char max
payment_source_token string Required	Unique identifier of the payment source. Allowable Values: 36 char max Existing payment source token
amount_category string Required	A category used to determine the actual payment amount. Allowable Values: `FIXED`, `MINIMUM_PAYMENT`, `REMAINING_STATEMENT_BALANCE`, `CURRENT_BALANCE`
amount decimal Optional	Amount of the payment. Required if `amount_category` is `FIXED`. Allowable Values: Format: 0.00
frequency string Required	Defines how often to make a scheduled payment. Allowable Values: `ONCE`, `MONTHLY`
payment_day string Optional	Day on which monthly payments are made. Required if `frequency` is `MONTHLY`. Allowable Values: `PAYMENT_DUE_DAY`
next_payment_impact_date date Optional	Date to make a one-time payment. Required if frequency is `ONCE`. Allowable Values: Format: yyyy-MM-dd
currency_code string Required	Valid three-digit ISO 4217 currency code. Allowable Values: `USD`
description string Optional	Description of the payment schedule. Allowable Values: 255 char max

Sample request body

JSON

{
  "token": "payment_schedule_token_1239",
  "payment_source_token": "payment_source_token_1112",
  "amount_category": "FIXED",
  "amount": 100,
  "frequency": "MONTHLY",
  "payment_day": "PAYMENT_DUE_DAY",
  "currency_code": "USD",
  "description": "Account statement payment"
}

Response body

Fields	Description
token string Returned	Unique identifier of the payment schedule. Allowable Values: 36 char max
payment_source_token string Returned	Unique identifier of a payment source. Allowable Values: Existing payment source token
account_token string Returned	Unique identifier of the credit account on which the payment schedule is made. Allowable Values: Existing account token
amount_category string Returned	A category used to determine the actual payment amount. Allowable Values: `FIXED`, `MINIMUM_PAYMENT`, `REMAINING_STATEMENT_BALANCE`, `CURRENT_BALANCE`
status string Returned	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
amount decimal Conditionally returned	Amount of the payment. Returned if the `amount_category` is `FIXED`. Allowable Values: Format: 0.00
frequency string Returned	Defines how often to make a scheduled payment. Allowable Values: `ONCE`, `MONTHLY`
payment_day string Conditionally returned	Day on which monthly payments are made. Returned if the `frequency` is `MONTHLY`. Allowable Values: `PAYMENT_DUE_DAY`
next_payment_impact_date date Conditionally returned	Date to make a one-time payment. Returned if `frequency` is `ONCE`. Allowable Values: Format: yyyy-MM-dd
currency_code string Returned	Valid three-digit ISO 4217 currency code. Allowable Values: `USD`
description string Conditionally returned	Description of the payment schedule. Allowable Values: 255 char max
created_time datetime Conditionally returned	Date and time when the payment schedule was created on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
updated_time datetime Conditionally returned	Date and time when the payment schedule was last updated on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "4749ab00-fec1-471c-ac5b-b8d31d06d7e4",
  "account_token": "12f10563-d5f2-11ec-889b-bd3a73e55331",
  "payment_source_token": "7d68f45b-1232-4283-a0ea-6b0418d37692",
  "amount_category": "FIXED",
  "status": "COMPLETED",
  "amount": 2500,
  "frequency": "ONCE",
  "next_payment_impact_date": "2024-01-31",
  "currency_code": "USD",
  "description": "Scheduled account payment",
  "created_time": "2024-01-12T15:03:09.717Z"
}

List payment schedules

Action: GET
Endpoint: /credit/accounts/{account_token}/paymentschedules Retrieve an array of payment schedules on a specific credit account. This endpoint supports sorting and pagination.

URL path parameters

Fields	Description
account_token string Required	Unique identifier of the credit account for which you want to retrieve payment schedules. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token

URL query parameters

Fields	Description
statuses array of strings Optional	Status of the payment schedules to retrieve. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
frequency array of strings Optional	Frequency of the payment schedules to retrieve. Allowable Values: `ONCE`, `MONTHLY`
count integer Optional	Number of payment schedule resources to retrieve. Allowable Values: 1 min
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: 0 min
sort_by string Optional	Field on which to sort. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. NOTE: You must sort using system field names such as `lastModifiedTime`, and not by the field names appearing in response bodies such as `last_modified_time`. Allowable Values: `lastModifiedTime`, `-lastModifiedTime`

Response body

Fields	Description
count integer Returned	Number of resources returned. Allowable Values: 1-10
start_index integer Returned	Sort order index of the first resource in the returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. Allowable Values: Any integer
is_more boolean Returned	A value of `true` indicates that more unreturned resources exist. Allowable Values: `true`, `false`
data array of objects Returned	List of payment schedules. Allowable Values: Valid array of one or more payment schedule objects
data[].token string Returned	Unique identifier of the payment schedule. Allowable Values: 36 char max
data[].payment_source_token string Returned	Unique identifier of a payment source. Allowable Values: Existing payment source token
data[].account_token string Returned	Unique identifier of the credit account on which the payment schedule is made. Allowable Values: Existing account token
data[].amount_category string Returned	A category used to determine the actual payment amount. Allowable Values: `FIXED`, `MINIMUM_PAYMENT`, `REMAINING_STATEMENT_BALANCE`, `CURRENT_BALANCE`
data[].status string Returned	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
data[].amount decimal Conditionally returned	Amount of the payment. Returned if the `amount_category` is `FIXED`. Allowable Values: Format: 0.00
data[].frequency string Returned	Defines how often to make a scheduled payment. Allowable Values: `ONCE`, `MONTHLY`
data[].payment_day string Conditionally returned	Day on which monthly payments are made. Returned if the `frequency` is `MONTHLY`. Allowable Values: `PAYMENT_DUE_DAY`
data[].next_payment_impact_date date Conditionally returned	Date to make a one-time payment. Returned if `frequency` is `ONCE`. Allowable Values: Format: yyyy-MM-dd
data[].currency_code string Returned	Valid three-digit ISO 4217 currency code. Allowable Values: `USD`
data[].description string Conditionally returned	Description of the payment schedule. Allowable Values: 255 char max
data[].created_time datetime Conditionally returned	Date and time when the payment schedule was created on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].updated_time datetime Conditionally returned	Date and time when the payment schedule was last updated on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "mytoken",
      "payment_source_token": "source1",
      "account_token": "account1",
      "amount_category": "REMAINING_STATEMENT_BALANCE",
      "status": "ACTIVE",
      "amount": null,
      "frequency": "MONTHLY",
      "payment_day": "PAYMENT_DUE_DAY",
      "next_payment_impact_date": "2023-08-31",
      "currency_code": "USD",
      "description": "Sample payoff",
      "created_time": "2023-08-22T22:17:11.407Z",
      "updated_time": "2023-08-22T22:17:11.407Z"
    },
    {
      "token": "mytoken1",
      "payment_source_token": "source1",
      "account_token": "account1",
      "amount_category": "FIXED",
      "status": "COMPLETED",
      "amount": 100,
      "frequency": "ONCE",
      "payment_day": "PAYMENT_DUE_DAY",
      "next_payment_impact_date": "2023-08-10",
      "currency_code": "USD",
      "description": "Sample payment",
      "created_time": "2023-07-22T22:13:31.426Z",
      "updated_time": "2023-07-22T22:13:31.426Z"
    }
  ]
}

Retrieve payment schedule

Action: GET
Endpoint: /credit/accounts/{account_token}/paymentschedules/{payment_schedule_token} Retrieve a single payment schedule on a specific credit account.

URL path parameters

Fields	Description
account_token string Required	Unique identifier of the credit account for which you want to retrieve a payment schedule. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
payment_schedule_token string Required	Unique identifier of the payment schedule that you want to retrieve. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token

Response body

Fields	Description
token string Returned	Unique identifier of the payment schedule. Allowable Values: 36 char max
payment_source_token string Returned	Unique identifier of a payment source. Allowable Values: Existing payment source token
account_token string Returned	Unique identifier of the credit account on which the payment schedule is made. Allowable Values: Existing account token
amount_category string Returned	A category used to determine the actual payment amount. Allowable Values: `FIXED`, `MINIMUM_PAYMENT`, `REMAINING_STATEMENT_BALANCE`, `CURRENT_BALANCE`
status string Returned	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
amount decimal Conditionally returned	Amount of the payment. Returned if the `amount_category` is `FIXED`. Allowable Values: Format: 0.00
frequency string Returned	Defines how often to make a scheduled payment. Allowable Values: `ONCE`, `MONTHLY`
payment_day string Conditionally returned	Day on which monthly payments are made. Returned if the `frequency` is `MONTHLY`. Allowable Values: `PAYMENT_DUE_DAY`
next_payment_impact_date date Conditionally returned	Date to make a one-time payment. Returned if `frequency` is `ONCE`. Allowable Values: Format: yyyy-MM-dd
currency_code string Returned	Valid three-digit ISO 4217 currency code. Allowable Values: `USD`
description string Conditionally returned	Description of the payment schedule. Allowable Values: 255 char max
created_time datetime Conditionally returned	Date and time when the payment schedule was created on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
updated_time datetime Conditionally returned	Date and time when the payment schedule was last updated on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "4749ab00-fec1-471c-ac5b-b8d31d06d7e4",
  "account_token": "12f10563-d5f2-11ec-889b-bd3a73e55331",
  "payment_source_token": "7d68f45b-1232-4283-a0ea-6b0418d37692",
  "amount_category": "FIXED",
  "status": "COMPLETED",
  "amount": 2500,
  "frequency": "ONCE",
  "next_payment_impact_date": "2024-01-31",
  "currency_code": "USD",
  "description": "Scheduled account payment",
  "created_time": "2024-01-12T15:03:09.717Z"
}

Create payment schedule transition

Action: POST
Endpoint: /credit/accounts/{account_token}/paymentschedules/{payment_schedule_token}/transitions Transition a payment schedule to a new status.

URL path parameters

Fields	Description
account_token string Required	Unique identifier of the credit account on which to transition a payment schedule. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
payment_schedule_token string Required	Unique identifier of the payment schedule whose status is to transition. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token

Request body

Fields	Description
token string Optional	Unique identifier of the payment schedule transition. Allowable Values: 36 char max
status string Required	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`

Sample request body

JSON

{
  "token": "4749ab00-fec1-471c-ac5b-b8d31d06d7e4",
  "status": "TERMINATED"
}

Response body

Fields	Description
token string Conditionally returned	Unique identifier of the payment schedule transition. Allowable Values: 36 char max
account_token string Conditionally returned	Unique identifier of the credit account on which to transition a payment schedule. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
payment_schedule_token string Conditionally returned	Unique identifier of the payment schedule whose status is to transition. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token
status string Conditionally returned	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
created_time datetime Conditionally returned	Date and time when the payment schedule transition was created on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
updated_time datetime Conditionally returned	Date and time when the payment schedule transition was last updated on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "payment_schedule_transition_token_111",
  "account_token": "credit_account_token_1232",
  "payment_schedule_token": "payment_schedule_token_1232",
  "status": "TERMINATED",
  "created_time": "2024-01-12T15:03:09.717Z",
  "updated_time": "2024-01-12T15:03:09.717Z"
}

Retrieve payment schedule transitions

Action: GET
Endpoint: /credit/accounts/{account_token}/paymentschedules/{payment_schedule_token}/transitions Retrieve an array of payment schedule transitions on a specific credit account.

URL path parameters

Fields	Description
account_token string Required	Unique identifier of the credit account for which you want to retrieve payment schedule transitions. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
payment_schedule_token string Required	Unique identifier of the payment schedule for which you want to retrieve transitions. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token

URL query parameters

Fields	Description
count integer Optional	Number of payment schedule resources to retrieve. Allowable Values: 1 min
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: 0 min
sort_by string Optional	Field on which to sort. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. NOTE: You must sort using system field names such as `createdTime`, and not by the field names appearing in response bodies such as `created_time`. Allowable Values: `createdTime`, `-createdTime`

Response body

Fields	Description
count integer Returned	Number of resources returned. Allowable Values: 1-10
start_index integer Returned	Sort order index of the first resource in the returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. Allowable Values: Any integer
is_more boolean Returned	A value of `true` indicates that more unreturned resources exist. Allowable Values: `true`, `false`
data array of objects Returned	List of payment schedule transitions. Allowable Values: Valid array of one or more payment schedule transition objects
data[].token string Conditionally returned	Unique identifier of the payment schedule transition. Allowable Values: 36 char max
data[].account_token string Conditionally returned	Unique identifier of the credit account on which to transition a payment schedule. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
data[].payment_schedule_token string Conditionally returned	Unique identifier of the payment schedule whose status is to transition. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token
data[].status string Conditionally returned	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
data[].created_time datetime Conditionally returned	Date and time when the payment schedule transition was created on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].updated_time datetime Conditionally returned	Date and time when the payment schedule transition was last updated on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "transition1",
      "account_token": "account1",
      "payment_schedule_token": "payment1",
      "status": "TERMINATED",
      "created_time": "2023-08-23T11:25:34.342Z",
      "updated_time": "2023-08-23T11:25:34.342Z"
    },
    {
      "token": "transition2",
      "account_token": "account2",
      "payment_schedule_token": "payment2",
      "status": "ACTIVE",
      "created_time": "2023-08-22T22:17:11.407Z",
      "updated_time": "2023-08-22T22:17:11.407Z"
    }
  ]
}

Retrieve payment schedule transition

Action: GET
Endpoint: /credit/accounts/{account_token}/paymentschedules/{payment_schedule_token}/transitions/{token} Retrieve a single payment schedule transition on a specific credit account.

URL path parameters

Fields	Description
account_token string Required	Unique identifier of the credit account for which you want to retrieve a payment schedule transition. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
payment_schedule_token string Required	Unique identifier of the payment schedule you want to retrieve. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token
token string Required	Unique identifier of the payment schedule transition you want to retrieve. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules/{payment_schedule_token}/transitions` to retrieve existing payment schedule transition tokens. Allowable Values: Existing payment schedule transition token

Response body

Fields	Description
token string Conditionally returned	Unique identifier of the payment schedule transition. Allowable Values: 36 char max
account_token string Conditionally returned	Unique identifier of the credit account on which to transition a payment schedule. Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens. Allowable Values: Existing account token
payment_schedule_token string Conditionally returned	Unique identifier of the payment schedule whose status is to transition. Send a `GET` request to `/credit/accounts/{account_token}/paymentschedules` to retrieve existing payment schedule tokens. Allowable Values: Existing payment schedule token
status string Conditionally returned	Status of the payment schedule. Allowable Values: `ACTIVE`, `COMPLETED`, `TERMINATED`
created_time datetime Conditionally returned	Date and time when the payment schedule transition was created on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
updated_time datetime Conditionally returned	Date and time when the payment schedule transition was last updated on Marqeta’s credit platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "transition2",
  "account_token": "account1",
  "payment_schedule_token": "payment1",
  "status": "ACTIVE",
  "created_time": "2023-08-22T22:17:11.407Z",
  "updated_time": "2023-08-22T22:17:11.407Z"
}

​Create payment schedule

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​List payment schedules

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve payment schedule

​URL path parameters

​Response body

​Sample response body

​Create payment schedule transition

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve payment schedule transitions

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve payment schedule transition

​URL path parameters

​Response body

​Sample response body

Create payment schedule

URL path parameters

Request body

Sample request body

Response body

Sample response body

List payment schedules

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve payment schedule

URL path parameters

Response body

Sample response body

Create payment schedule transition

URL path parameters

Request body

Sample request body

Response body

Sample response body

Retrieve payment schedule transitions

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve payment schedule transition

URL path parameters

Response body

Sample response body