Skip to main content
Use the account refunds endpoints to create and retrieve account refunds on Marqeta’s credit platform. You can issue account refunds to your cardholders with negative account balances. The maximum refund amount is the amount that brings the account balance to 0.Forexample,0. For example, 4000 is the maximum refund amount for a -$4000 account balance.

​
Create refund

Action: POST
Endpoint: /credit/accounts/{account_token}/refunds Create a new refund, which you can issue to the account holder if their credit account balance is negative.

​
URL path parameters

FieldsDescription
account_token

string

Required		Unique identifier of the credit account for which you want to create a balance refund.

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 refund.

Allowable Values:

36 char max
method

string

Required		Payment instrument used to issue the refund.

Allowable Values:

ACH, CHECK
type

string

Required		Type of refund.

Allowable Values:

PAYMENT_REFUND, CREDIT_BALANCE_REFUND
payment_source_token

string

Optional		Unique identifier of the payment source that receives the refunded amount.

Allowable Values:

36 char max

Existing payment source token
amount

decimal

Optional		Amount of the refund.

The maximum refund amount is the amount that brings the account balance to 0.Forexample,0. For example, 4000 is the maximum refund amount for a -$4000 account balance.

Allowable Values:

0.01 min
currency_code

string

Optional		Valid three-digit ISO 4217 currency code.

Allowable Values:

USD
description

string

Optional		Description of the refund.

Allowable Values:

255 char max

​
Sample request body

JSON
{
  "method": "ACH",
  "type": "CREDIT_BALANCE_REFUND",
  "payment_source_token": "my_payment_funding_source_token",
  "description": "credit refund"
}

​
Response body

FieldsDescription
token

string

Returned		Unique identifier of the refund.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the account for which the refund is issued.

Allowable Values:

36 char max

Existing account token
status

string

Returned		Current status of the refund.

Allowable Values:

INITIATED, PENDING, PROCESSING, SUBMITTED, CANCELLED, COMPLETED, RETURNED
method

string

Returned		Payment instrument used to issue the refund.

Allowable Values:

ACH, CHECK
type

string

Returned		Type of refund.

Allowable Values:

PAYMENT_REFUND, CREDIT_BALANCE_REFUND
payment_source_token

string

Conditionally returned		Unique identifier of the payment source that receives the refunded amount.

Allowable Values:

36 char max

Existing payment source token
amount

decimal

Returned		Amount of the refund.

The maximum refund amount is the amount that brings the account balance to 0.Forexample,0. For example, 4000 is the maximum refund amount for a -$4000 account balance.

Allowable Values:

0.01 min
currency_code

string

Returned		Valid three-digit ISO 4217 currency code.

Allowable Values:

USD
description

string

Conditionally returned		Description of the refund.

Allowable Values:

255 char max
created_time

datetime

Returned		Date and time when the refund was created.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
updated_time

datetime

Returned		Date and time when the refund was last updated.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "token": "credit_balance_refund_token1234",
  "account_token": "my_account_token_12",
  "status": "PENDING",
  "method": "ACH",
  "type": "CREDIT_BALANCE_REFUND",
  "payment_source_token": "my_payment_funding_source_token",
  "amount": 10,
  "currency_code": "USD",
  "description": "credit balance refund",
  "created_time": "2025-01-02T20:17:28Z",
  "updated_time": "2025-01-02T20:17:28Z"
}

​
List account refunds

Action: GET
Endpoint: /credit/accounts/{account_token}/refunds Use the /credit/accounts/{account_token}/refunds endpoint to retrieve an array of refunds on a credit account. This endpoint supports sorting and pagination.

​
URL path parameters

FieldsDescription
account_token

string

Required		Unique identifier of the credit account for which to retrieve refunds.

Send a GET request to /credit/accounts to retrieve existing credit account tokens.

Allowable Values:

Existing account token

​
URL query parameters

FieldsDescription
start_date

date

Optional		Beginning of the date range of the refunds to return.

Allowable Values:

Format: yyyy-MM-dd
end_date

date

Optional		End of the date range of the refunds to return.

Allowable Values:

Format: yyyy-MM-dd
count

integer

Optional		Number of account refund resources to retrieve.

Allowable Values:

1–100
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. Only supports lastModifiedTime and -lastModifiedTime.

NOTE: You must sort using system field names such as lastModifiedTime, and not by the field names appearing in response bodies such as updated_time.

Allowable Values:

lastModifiedTime, -lastModifiedTime
statuses

array of strings

Optional		Array of statuses by which to filter refunds.

Allowable Values:

INITIATED, PENDING, PROCESSING, SUBMITTED, CANCELLED, COMPLETED, RETURNED

​
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		Contains one or more refunds on a credit account.

Allowable Values:

One or more refund objects
data[].token

string

Returned		Unique identifier of the refund.

Allowable Values:

36 char max
data[].account_token

string

Returned		Unique identifier of the account for which the refund is issued.

Allowable Values:

36 char max

Existing account token
data[].status

string

Returned		Current status of the refund.

Allowable Values:

INITIATED, PENDING, PROCESSING, SUBMITTED, CANCELLED, COMPLETED, RETURNED
data[].method

string

Returned		Payment instrument used to issue the refund.

Allowable Values:

ACH, CHECK
data[].type

string

Returned		Type of refund.

Allowable Values:

PAYMENT_REFUND, CREDIT_BALANCE_REFUND
data[].payment_source_token

string

Conditionally returned		Unique identifier of the payment source that receives the refunded amount.

Allowable Values:

36 char max

Existing payment source token
data[].amount

decimal

Returned		Amount of the refund.

The maximum refund amount is the amount that brings the account balance to 0.Forexample,0. For example, 4000 is the maximum refund amount for a -$4000 account balance.

Allowable Values:

0.01 min
data[].currency_code

string

Returned		Valid three-digit ISO 4217 currency code.

Allowable Values:

USD
data[].description

string

Conditionally returned		Description of the refund.

Allowable Values:

255 char max
data[].created_time

datetime

Returned		Date and time when the refund was created.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
data[].updated_time

datetime

Returned		Date and time when the refund was last updated.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "count": 2,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data": [
    {
      "token": "credit_balance_refund_token1234",
      "account_token": "my_account_token_12",
      "status": "PENDING",
      "method": "ACH",
      "type": "CREDIT_BALANCE_REFUND",
      "payment_source_token": "my_payment_funding_source_token",
      "amount": 10,
      "currency_code": "USD",
      "description": "credit balance refund",
      "created_time": "2025-01-02T20:17:28Z",
      "updated_time": "2025-01-02T20:17:28Z"
    },
    {
      "token": "credit_balance_refund_token12",
      "account_token": "my_account_token_34",
      "status": "COMPLETED",
      "method": "CHECK",
      "type": "CREDIT_BALANCE_REFUND",
      "amount": 10,
      "currency_code": "USD",
      "description": "credit balance refund",
      "created_time": "2025-01-02T20:17:28Z",
      "updated_time": "2025-01-02T20:17:28Z"
    }
  ]
}

​
Retrieve account refund

Action: GET
Endpoint: /credit/accounts/{account_token}/refunds/{refund_token} Use the /accounts/{account_token}/refunds/{refund_token} endpoint to retrieve a refund.

​
URL path parameters

FieldsDescription
account_token

string

Required		Unique identifier of the credit account for which to retrieve a refund.

Send a GET request to /credit/accounts to retrieve existing credit account tokens.

Allowable Values:

Existing account token
refund_token

string

Required		Unique identifier of the refund to retrieve.

Send a GET request to /credit/accounts/{account_token}/refunds/{refund_token} to retrieve existing refunds.

Allowable Values:

Existing refund token

​
Response body

FieldsDescription
token

string

Returned		Unique identifier of the refund.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the account for which the refund is issued.

Allowable Values:

36 char max

Existing account token
status

string

Returned		Current status of the refund.

Allowable Values:

INITIATED, PENDING, PROCESSING, SUBMITTED, CANCELLED, COMPLETED, RETURNED
method

string

Returned		Payment instrument used to issue the refund.

Allowable Values:

ACH, CHECK
type

string

Returned		Type of refund.

Allowable Values:

PAYMENT_REFUND, CREDIT_BALANCE_REFUND
payment_source_token

string

Conditionally returned		Unique identifier of the payment source that receives the refunded amount.

Allowable Values:

36 char max

Existing payment source token
amount

decimal

Returned		Amount of the refund.

The maximum refund amount is the amount that brings the account balance to 0.Forexample,0. For example, 4000 is the maximum refund amount for a -$4000 account balance.

Allowable Values:

0.01 min
currency_code

string

Returned		Valid three-digit ISO 4217 currency code.

Allowable Values:

USD
description

string

Conditionally returned		Description of the refund.

Allowable Values:

255 char max
created_time

datetime

Returned		Date and time when the refund was created.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
updated_time

datetime

Returned		Date and time when the refund was last updated.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

​
Sample response body

JSON
{
  "token": "credit_balance_refund_token1234",
  "account_token": "my_account_token_12",
  "status": "PENDING",
  "method": "ACH",
  "type": "CREDIT_BALANCE_REFUND",
  "payment_source_token": "my_payment_funding_source_token",
  "amount": 10,
  "currency_code": "USD",
  "description": "credit balance refund",
  "created_time": "2025-01-02T20:17:28Z",
  "updated_time": "2025-01-02T20:17:28Z"
}

​
Transition account refund status

Action: POST
Endpoint: /credit/accounts/{account_token}/refunds/{refund_token}/transitions Use the /accounts/{account_token}/refunds/{refund_token}/transitions endpoint to transition a credit account refund’s status to a new status.

​
URL path parameters

FieldsDescription
account_token

string

Required		Unique identifier of the credit account for which you want to transition a refund status. Send a GET request to /credit/accounts to retrieve existing credit account tokens.

Allowable Values:

Existing account token
refund_token

string

Required		Unique identifier of the refund whose status you want to transition. Send a GET request to /credit/accounts/{account_token}/refunds endpoint to retrieve existing refund tokens for a given account.

Allowable Values:

Existing refund token

​
Request body

FieldsDescription
token

string

Optional		Unique identifier of the refund status transition.

Allowable Values:

36 char max
status

string

Required		Current status of the refund.

Allowable Values:

INITIATED, PENDING, PROCESSING, SUBMITTED, CANCELLED, COMPLETED, RETURNED

​
Sample request body

JSON
{
  "status": "SUBMITTED"
}

​
Response body

FieldsDescription
token

string

Returned		Unique identifier of the refund.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the account for which the refund is issued.

Allowable Values:

36 char max

Existing account token
status

string

Returned		Current status of the refund.

Allowable Values:

INITIATED, PENDING, PROCESSING, SUBMITTED, CANCELLED, COMPLETED, RETURNED
method

string

Returned		Payment instrument used to issue the refund.

Allowable Values:

ACH, CHECK
type

string

Returned		Type of refund.

Allowable Values:

PAYMENT_REFUND, CREDIT_BALANCE_REFUND
payment_source_token

string

Conditionally returned		Unique identifier of the payment source that receives the refunded amount.

Allowable Values:

36 char max

Existing payment source token
amount

decimal

Returned		Amount of the refund.

The maximum refund amount is the amount that brings the account balance to 0.Forexample,0. For example, 4000 is the maximum refund amount for a -$4000 account balance.

Allowable Values:

0.01 min
currency_code

string

Returned		Valid three-digit ISO 4217 currency code.

Allowable Values:

USD
description

string

Conditionally returned		Description of the refund.

Allowable Values:

255 char max
created_time

datetime

Returned		Date and time when the refund was created.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
updated_time

datetime

Returned		Date and time when the refund was last updated.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

Related topics

Balance RefundsFee RefundsCheck ReturnsAbout Credit Account Ledger EntriesAbout Credit Accounts