Skip to main content
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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

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

Related topics

PaymentsPayment SourcesCredit PaymentsAbout Credit Account PaymentsPush-to-Card Payments