/
10 minute read
March 24, 2022

About Credit Account Payments

A payment is an amount paid toward the account balance to reduce the total amount owed on a credit account. The Marqeta 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 the Marqeta platform.

  • What payment sources are and how to establish them.

  • The payment lifecycle.

  • How to configure a payment hold.

  • How the Marqeta platform handles canceled, 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 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.

Payment statuses

Each payment has a status that defines which actions it can take. Payments transition between statuses during their lifetime.

  • 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 canceled.

  • 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 canceled.

  • 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 canceled.

  • 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 the Marqeta 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.

The payment lifecycle

ACH Payments always start in INITIATED status and move to PENDING shortly after the ACH processor acknowledges its receipt. PENDING payments can move to either PROCESSING or CANCELLED. 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.

Non-ACH payments always start and end in COMPLETED status since it is assumed that the payment has cleared. Non-ACH payments cannot be canceled. If the payment fails, you must manually transition the payment to RETURNED. For more on how to transition a payment, see Returns later 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 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 the Marqeta platform so that it impacts the credit account ledger appropriately.

For more on initiating a payment, see Create account 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, 1, 3, 5, or 7 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.

Cancelations, 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.

Cancelations (ACH payments only)

You can cancel a pending ACH payment. However, once a payment has moved into processing, it cannot be canceled.

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 the Marqeta 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 the Marqeta 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 canceled payment can also trigger additional business logic, such as interest re-calculations 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

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

  • 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 canceled.

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
Copied

Is this helpful?

Yes
No

For the complete 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 canceled. For more on possible status transitions, see The payment lifecycle earlier on this page.

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

JSON
Copied

Is this helpful?

Yes
No

For the complete endpoint reference, see Transition account payment status.

Join our developer newsletter