About Credit Account Payments

A payment is an amount paid toward the account balance to reduce the total amount owed on a credit account. Marqeta’s credit platform enables ACH payments to be made from a linked payment source. Marqeta also supports and maintains the system of record for the non-ACH payment methods of cash, check, and debit. At the end of this guide, you should understand:

What payments are and how they are relevant to Marqeta’s credit platform.
What payment sources are and how to establish them.
The payment lifecycle.
How to configure a payment hold.
How Marqeta’s credit platform handles cancelled, returned, and refunded payments.
The impact different payment statuses have on the account ledger.
The payment events you can configure a webhook to capture.

Payment sources

The following applies to ACH payments processed by Marqeta only. Payment sources are external accounts from which funds are withdrawn to make ACH payments on a credit account. Before making an ACH payment, you must have established a link between a payment source and the credit account. Multiple payment sources can be linked to a single credit account.

Note
Before you can use the credit/paymentsources endpoint, Marqeta must first set up your receivables account. Contact your Marqeta representative prior to using the payment sources endpoint for the first time.

Use the credit/paymentsources endpoint to establish a payment source and link it to an existing credit account. For the complete endpoint reference, see Payment Sources.

Verification override

Note
Marqeta does not handle verification and expects you to verify payment sources.

When creating a payment source, set the verification_override field to true if the external source account has been verified. You can include a verification token in the value for verification_notes, along with any information associated with your verification process. If the external payment source has not been verified, set verification_override to false.

Payment source status

A payment source can be in ACTIVE or INACTIVE status. To make a payment source active or inactive, send a PUT request to the /credit/paymentsources/{token} endpoint with the status field set to ACTIVE or INACTIVE. For more, see Update payment source.

The payment lifecycle

Payments transition between several statuses during their lifetime. Its status defines which actions a payment can take.

Name	Description
`INITIATED` (ACH payments only)	The request to initiate a payment has been received and the payment is awaiting creation.
`PENDING` (ACH payments only)	The request to initiate a payment has been received and the payment has been created. Pending payments can be cancelled.
`PROCESSING` (ACH payments only)	The payment is currently being processed for submission to the bank.
`SUBMITTED` (ACH payments only)	The payment has been submitted to the bank. Submitted payments cannot be cancelled.
`COMPLETED`	The payment has been completed and the credit account balance has been reduced by the payment amount.
`CANCELLED` (ACH payments only)	A pending payment has been cancelled.
`RETURNED`	For ACH payments, a completed payment has been returned by the ACH network; can be due to insufficient funds, account closure, or more. For non-ACH payments, the payment was returned by Marqeta’s credit platform; commonly due to a bounced check.
`REFUNDED`	The payment has been refunded by check.
`SYS_ERROR`	An error occurred when initiating a payment. In this case, you can try initiating the payment again.
`ACH_ERROR` (ACH payments only)	An error occurred when processing the payment. In this case, Marqeta and the ACH processor will attempt to reprocess the payment and no further action is needed from you.

ACH payment transitions

ACH Payments always start in INITIATED and move to PENDING shortly after the ACH processor acknowledges its receipt. PENDING payments can move to PROCESSING or be manually transitioned to CANCELLED, a terminal status. From PROCESSING, a payment can move to SUBMITTED, and then to COMPLETED, typically a terminal status. However, if the ACH processor cannot complete the payment, COMPLETED payments can move to RETURNED, a terminal status. If the payment was refunded by check, you must manually transition the payment status from COMPLETED to REFUNDED, a terminal status. For more on cancelled, returned, and refunded payments, see Cancellations, returns, and refunds in this guide. The following diagram outlines the possible transitions between statuses for an ACH payment.

Possible transitions between payment states

Non-ACH payment transitions

Non-ACH payments always start and end in COMPLETED status since it is assumed that the payment has cleared. Non-ACH payments cannot be cancelled. If the payment fails, you must manually transition the payment to RETURNED, a terminal status. If the payment was refunded by check, you must manually transition the payment to REFUNDED, a terminal status. For more on cancelled, returned, and refunded payments, see Cancellations, returns, and refunds in this guide.

Payment creation

To create a payment, send a POST request to the /credit/accounts/{token}/payments endpoint with the following fields defined:

method – For ACH payments, set to ACH. For non-ACH payments, set to CHECK, DEBIT, or CASH.
payment_source_token (ACH payments processed by Marqeta only) – Set to the value of the payment source token. For more, see Payment sources earlier in this guide.

Note
Marqeta does not process non-ACH payments. However, if you have processed a non-ACH payment, you must create that payment on Marqeta’s credit platform so that it impacts the credit account ledger appropriately.

For more on initiating a payment, see Create account payment.

Payment schedules

You can schedule a one-time or recurring payment to occur on a specific date or frequency. To create a payment schedule, send a POST request to the /credit/accounts/{account_token}/paymentschedules endpoint. For more, see Payment Schedules.

Condition for processing scheduled payments

Creating a payment schedule does not guarantee that a payment is processed. Scheduled payments are processed only if the account is carrying a balance from the previous statement on the payment due day. For example, a scheduled payment won’t be processed if all four of the following statements are true on the payment due day:

The amount_category value is REMAINING_STATEMENT_BALANCE
The frequency value is MONTHLY
Payments made or credits received in the current statement cycle brought the account balance to $0 or negative
The previous statement balance was paid off so that the opening balance of the current statement was $0 at the start of the current statement cycle

In the above example, a payment is scheduled to pay off the remaining statement balance each month. If the balance is already paid off before the payment due day, the system does not detect a balance and does not process the scheduled payment.

Payment holds

A payment hold occurs when a payment transitions to a completed state but the increase in available credit is held for a specified number of days. If a payment hold is not configured, the available credit increases immediately after a payment is completed.

Configuring payment holds

You can configure a payment hold during account creation by defining the fields in the config.payment_holds object. Specify the number of hold days in ach_hold_days for ACH payments and in check_hold_days for non-ACH, check payments. Hold days can be 0-30 business days. For more, see Create account.

Updating payment hold configurations

You can update payment hold configurations on an account by passing the config.payment_holds object in a PUT request to the /credit/accounts/{token} endpoint. For more, see Update account. Updates to payment hold configurations only affect payments created after the update. Existing payment holds keep their current release schedule, unless manually released.

Releasing a payment hold

You can manually release the hold on a payment by sending a POST request to the /credit/accounts/{account_token}/payments/{payment_token}/releasehold endpoint. For more, see Release payment hold.

Identifying a payment hold

To see if a payment is on hold, send a GET request to the /credit/accounts/{token}/payments/{payment_token} endpoint and check the on_hold field in the response. A value of true indicates that the payment is on hold. The following fields also appear in the response:

hold_days - The number of days a payment is on hold. For example, a hold_days value of 3 indicates that the payment is being held for three business days. The hold on available credit begins when a payment transitions to a completed state.
hold_end_time – Indicates the date and time a payment hold is scheduled to end. The available credit increase occurs at this time.
is_manual_release – A value of true indicates that the payment was manually released from its hold.

For more, see Release payment hold.

Cancellations, returns, and refunds

You can cancel, return, or refund a payment by transitioning the payment’s status. For the complete endpoint reference, see Transition account payment status.

Cancellations (ACH payments only)

You can cancel a pending ACH payment. However, once a payment has moved into processing, it cannot be cancelled. To cancel a pending payment, send a POST request to /credit/accounts/{account_token}/payments/{payment_token}/transitions with the status set to CANCELLED.

Returns

Note
Marqeta does not process non-ACH payment returns. However, if you have returned a payment, you must transition that payment’s status to RETURNED on Marqeta’s credit platform so that it impacts the credit account ledger appropriately.

If you have returned a payment, send a POST request to /credit/accounts/{account_token}/payments/{payment_token}/transitions with the status set to RETURNED.

Refunds

A payment refund occurs when you refund a completed payment on a credit account. Currently, you must issue refunds for both ACH and non-ACH payments through a non-ACH method such as a check.

Note
Marqeta does not issue payment refunds. However, if you have refunded a payment, you must transition that payment’s status to refunded on Marqeta’s credit platform so that it impacts the credit account ledger appropriately.

If you have refunded a payment, send a POST request to /credit/accounts/{account_token}/payments/{payment_token}/transitions with the status set to REFUNDED.

Credit accounts ledger impact

The following table indicates how payment statuses impact your credit account ledger and its available credit.

Payment Status	Current Balance	Available Credit
`PENDING` (ACH payments only)	Decreases current balance.	None
`CANCELLED` (ACH payments only)	Increases current balance.	None
`COMPLETED`	For ACH payments: none. For non-ACH payments: decreases current balance.	Increases
`RETURNED`	Increases current balance.	Decreases
`REFUNDED`	Increases current balance.	Decreases

A returned or cancelled payment can also trigger additional business logic, such as interest recalculations or changes in how returned or late payment fees are applied. Non-ACH payments have an immediate impact on the credit account ledger and its available credit since it is assumed that the payment has cleared. If the payment is returned, the impact on the credit account and available credit is reversed.

Payment webhooks

Marqeta’s credit platform sends webhook notifications when certain payment activity occurs. You can configure a webhook to capture the following payment events:

Name	Description
`account.payment.initiated` (ACH payments only)	Payment was initiated.
`account.payment.pending` (ACH payments only)	Payment was successfully created.
`account.payment.processing` (ACH payments only)	Payment is being processed by the ACH processor.
`account.payment.submitted` (ACH payments only)	Payment was submitted to the bank.
`account.payment.completed`	Payment is completed.
`account.payment.returned`	Payment was returned.
`account.payment.refunded`	Payment was refunded.
`account.payment.cancelled` (ACH payments only)	Payment was cancelled.

For more on the events, see Credit account payment transition events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Tutorials

The following tutorials walk you through how to initiate, cancel, return, or refund a payment.

Initiate a payment

Send a POST request to the /credit/accounts/{token}/payments endpoint with the credit account token included in the URL query parameters and the following fields defined:

token — Set the value to a unique identifier of the payment.
method — For ACH payments, set to ACH. For non-ACH payments, set to CHECK, DEBIT, or CASH.
payment_source_token (ACH payments only) – Set to the value of the payment source token.
Send a GET request to /credit/paymentsources to retrieve existing payment source tokens. For more, see Payment sources earlier in this guide.
amount — Set the value to the amount of the payment.
currency_code — Set the value to the three-character ISO 4217 currency type of the payment.

The following code block shows a sample payment as it would appear in a request:

JSON

{
  "token": "my_payment_token_via_check",
  "method": "CHECK",
  "amount": 25,
  "currency_code": "USD",
  "description": "minimum payment",
  "metadata": "Check number 111222333"
}

For the endpoint reference, see Create account payment.

Cancel a payment (ACH payments only)

To cancel a payment, send a POST request to /credit/accounts/{account_token}/payments/{payment_token}/transitions with the credit account token and payment token included in the URL query parameters and the status field set to CANCELLED.

Note
You can cancel a pending ACH payment. However, once a payment has moved into processing, it cannot be cancelled. For more on possible status transitions, see The payment lifecycle earlier on this page.

The following code block shows a sample cancelled payment as it would appear in a request:

JSON

{
  "status": "CANCELLED"
}

For the endpoint reference, see Transition account payment status.

Guides

​Payment sources

​Verification override

​Payment source status

​The payment lifecycle

​ACH payment transitions

​Non-ACH payment transitions

​Payment creation

​Payment schedules

​Condition for processing scheduled payments

​Payment holds

​Configuring payment holds

​Updating payment hold configurations

​Releasing a payment hold

​Identifying a payment hold

​Cancellations, returns, and refunds

​Cancellations (ACH payments only)

​Returns

​Refunds

​Credit accounts ledger impact

​Payment webhooks

​Tutorials

​Initiate a payment

​Cancel a payment (ACH payments only)

Payment sources

Verification override

Payment source status

The payment lifecycle

ACH payment transitions

Non-ACH payment transitions

Payment creation

Payment schedules

Condition for processing scheduled payments

Payment holds

Configuring payment holds

Updating payment hold configurations

Releasing a payment hold

Identifying a payment hold

Cancellations, returns, and refunds

Cancellations (ACH payments only)

Returns

Refunds

Credit accounts ledger impact

Payment webhooks

Tutorials

Initiate a payment

Cancel a payment (ACH payments only)