> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# About Credit Account Payments
> Learn about how Marqeta's credit platform enables both ACH and non-ACH payments to be made on a credit account.
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](/core-api/credit-account-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](/core-api/credit-account-payment-sources/#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](/developer-guides/about-credit-account-payments/#_cancellations_returns_and_refunds) in this guide.
The following diagram outlines the possible transitions between statuses for an ACH payment.
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](/developer-guides/about-credit-account-payments/#_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](#_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](/core-api/credit-account-payments/#create_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](/core-api/credit-account-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](/core-api/credit-accounts/#create_credit_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](/core-api/credit-accounts/#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](/core-api/credit-account-payments/#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](/core-api/credit-account-payments/#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](/core-api/credit-account-payments/#transition_payment).
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](/core-api/event-types/#_credit_account_payment_transition_events). For more on subscribing to webhook notifications, see the About Webhooks [tutorial](/developer-guides/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](#_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 JSON lines wrap theme={null}
{
"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](/core-api/credit-account-payments/#create_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](#_the_payment_lifecycle) earlier on this page.
The following code block shows a sample cancelled payment as it would appear in a request:
```json JSON lines wrap theme={null}
{
"status": "CANCELLED"
}
```
For the endpoint reference, see [Transition account payment status](/core-api/credit-account-payments/#transition_payment).