Account Refunds

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

Fields	Description
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

Fields	Description
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. 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

Fields	Description
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. 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

Fields	Description
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

Fields	Description
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

Fields	Description
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. 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

Fields	Description
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

Fields	Description
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. 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

Fields	Description
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

Fields	Description
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

Fields	Description
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. 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

​Create refund

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​List account refunds

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve account refund

​URL path parameters

​Response body

​Sample response body

​Transition account refund status

​URL path parameters

​Request body

​Sample request body

​Response body

Create refund

URL path parameters

Request body

Sample request body

Response body

Sample response body

List account refunds

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve account refund

URL path parameters

Response body

Sample response body

Transition account refund status

URL path parameters

Request body

Sample request body

Response body