Marqeta Account Refunds API

openapi: 3.0.3
info:
  contact:
    email: support@marqeta.com
    name: Marqeta
  description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
  termsOfService: https://www.marqeta.com/api-terms
  title: Core accepted countries Account Refunds API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- description: '// Conditional snippet for beta or internal content

    include::../../maturity-admonition-banner.adoc[]


    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.'
  name: Account Refunds
paths:
  /accounts/{account_token}/refunds:
    get:
      description: 'Use the `/credit/accounts/{account_token}/refunds` endpoint to retrieve an array of refunds on a credit account.


        This endpoint supports <</core-api/sorting-and-pagination, sorting and pagination>>.'
      operationId: listRefunds
      parameters:
      - description: 'Unique identifier of the credit account for which to retrieve refunds.


          Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens.'
        explode: false
        in: path
        name: account_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing account token
        style: simple
      - description: Beginning of the date range of the refunds to return.
        explode: true
        in: query
        name: start_date
        required: false
        schema:
          format: date
          type: string
          x-allowableValues: 'Format: yyyy-MM-dd'
        style: form
      - description: End of the date range of the refunds to return.
        explode: true
        in: query
        name: end_date
        required: false
        schema:
          format: date
          type: string
          x-allowableValues: 'Format: yyyy-MM-dd'
        style: form
      - description: Number of account refund resources to retrieve.
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 5
          maximum: 100
          minimum: 1
          type: integer
        style: form
      - description: Sort order index of the first resource in the returned array.
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
        style: form
      - description: '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`.'
        explode: true
        in: query
        name: sort_by
        required: false
        schema:
          default: -lastModifiedTime
          enum:
          - lastModifiedTime
          - -lastModifiedTime
          type: string
        style: form
      - description: Array of statuses by which to filter refunds.
        explode: true
        in: query
        name: statuses
        required: false
        schema:
          items:
            $ref: '#/components/schemas/RefundStatus'
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              example:
                count: 2
                data:
                - account_token: my_account_token_12
                  amount: 10
                  created_time: 2025-01-02 20:17:28+00:00
                  currency_code: USD
                  description: credit balance refund
                  method: ACH
                  payment_source_token: my_payment_funding_source_token
                  status: PENDING
                  token: credit_balance_refund_token1234
                  type: CREDIT_BALANCE_REFUND
                  updated_time: 2025-01-02 20:17:28+00:00
                - account_token: my_account_token_34
                  amount: 10
                  created_time: 2025-01-02 20:17:28+00:00
                  currency_code: USD
                  description: credit balance refund
                  method: CHECK
                  status: COMPLETED
                  token: credit_balance_refund_token12
                  type: CREDIT_BALANCE_REFUND
                  updated_time: 2025-01-02 20:17:28+00:00
                end_index: 2
                is_more: false
                start_index: 0
              schema:
                $ref: '#/components/schemas/RefundsPage'
          description: Paginated list of refunds for the given token.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      security:
      - zionToken: []
      summary: List account refunds
      tags:
      - Account Refunds
    post:
      description: Create a new refund, which you can issue to the account holder if their credit account balance is negative.
      operationId: createRefund
      parameters:
      - description: '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.'
        explode: false
        in: path
        name: account_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing account token
        style: simple
      requestBody:
        content:
          application/json:
            example:
              description: credit refund
              method: ACH
              payment_source_token: my_payment_funding_source_token
              type: CREDIT_BALANCE_REFUND
            schema:
              $ref: '#/components/schemas/RefundCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                account_token: my_account_token_12
                amount: 10
                created_time: 2025-01-02 20:17:28+00:00
                currency_code: USD
                description: credit balance refund
                method: ACH
                payment_source_token: my_payment_funding_source_token
                status: PENDING
                token: credit_balance_refund_token1234
                type: CREDIT_BALANCE_REFUND
                updated_time: 2025-01-02 20:17:28+00:00
              schema:
                $ref: '#/components/schemas/RefundResponse'
          description: Expected response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      security:
      - zionToken: []
      summary: Create refund
      tags:
      - Account Refunds
  /accounts/{account_token}/refunds/{refund_token}:
    get:
      description: Use the `/accounts/{account_token}/refunds/{refund_token}` endpoint to retrieve a refund.
      operationId: retrieveRefund
      parameters:
      - description: '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.'
        explode: false
        in: path
        name: account_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing account token
        style: simple
      - description: 'Unique identifier of the refund to retrieve.


          Send a `GET` request to `/credit/accounts/{account_token}/refunds/{refund_token}` to retrieve existing refunds.'
        explode: false
        in: path
        name: refund_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing refund token
        style: simple
      responses:
        '200':
          content:
            application/json:
              example:
                account_token: my_account_token_12
                amount: 10
                created_time: 2025-01-02 20:17:28+00:00
                currency_code: USD
                description: credit balance refund
                method: ACH
                payment_source_token: my_payment_funding_source_token
                status: PENDING
                token: credit_balance_refund_token1234
                type: CREDIT_BALANCE_REFUND
                updated_time: 2025-01-02 20:17:28+00:00
              schema:
                $ref: '#/components/schemas/RefundResponse'
          description: Refund object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      security:
      - zionToken: []
      summary: Retrieve account refund
      tags:
      - Account Refunds
  /accounts/{account_token}/refunds/{refund_token}/transitions:
    post:
      description: Use the `/accounts/{account_token}/refunds/{refund_token}/transitions` endpoint to transition a credit account refund's status to a new status.
      operationId: transitionRefund
      parameters:
      - description: '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.'
        explode: false
        in: path
        name: account_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing account token
        style: simple
      - description: '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.'
        explode: false
        in: path
        name: refund_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing refund token
        style: simple
      requestBody:
        content:
          application/json:
            example:
              status: SUBMITTED
            schema:
              $ref: '#/components/schemas/RefundTransitionRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
          description: Refund Response object.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      security:
      - zionToken: []
      summary: Transition account refund status
      tags:
      - Account Refunds
components:
  schemas:
    RefundType:
      description: Type of refund.
      enum:
      - PAYMENT_REFUND
      - CREDIT_BALANCE_REFUND
      type: string
    CurrencyCode:
      default: USD
      description: Valid three-digit link:https://www.iso.org/iso-4217-currency-codes.html[ISO 4217 currency code, window="_blank"].
      enum:
      - USD
      type: string
    RefundCreateRequest:
      description: Specifies the details of a refund creation request.
      properties:
        amount:
          description: '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.'
          minimum: 0.01
          type: number
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        description:
          description: Description of the refund.
          type: string
        method:
          $ref: '#/components/schemas/RefundMethod'
        payment_source_token:
          description: Unique identifier of the payment source that receives the refunded amount.
          maxLength: 36
          type: string
        token:
          description: Unique identifier of the refund.
          type: string
        type:
          $ref: '#/components/schemas/RefundType'
      required:
      - method
      - type
      type: object
    RefundsPage:
      description: Returns paginated  list of refund resources.
      properties:
        count:
          description: Number of resources returned.
          type: integer
        data:
          description: Contains one or more refunds on a credit account.
          items:
            $ref: '#/components/schemas/RefundResponse'
          type: array
        end_index:
          description: Sort order index of the last resource in the returned array.
          type: integer
        is_more:
          description: A value of `true` indicates that more unreturned resources exist.
          type: boolean
        start_index:
          description: Sort order index of the first resource in the returned array.
          type: integer
      required:
      - count
      - data
      - end_index
      - is_more
      - start_index
      type: object
    RefundMethod:
      description: Payment instrument used to issue the refund.
      enum:
      - ACH
      - CHECK
      type: string
    RefundStatus:
      description: Current status of the refund.
      enum:
      - INITIATED
      - PENDING
      - PROCESSING
      - SUBMITTED
      - CANCELLED
      - COMPLETED
      - RETURNED
      type: string
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      type: object
    RefundResponse:
      description: Detailed refund response object.
      properties:
        account_token:
          description: Unique identifier of the account for which the refund is issued.
          maxLength: 36
          type: string
        amount:
          description: '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.'
          type: number
        created_time:
          description: Date and time when the refund was created.
          format: date-time
          type: string
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        description:
          description: Description of the refund.
          type: string
        method:
          $ref: '#/components/schemas/RefundMethod'
        payment_source_token:
          description: Unique identifier of the payment source that receives the refunded amount.
          maxLength: 36
          type: string
        status:
          $ref: '#/components/schemas/RefundStatus'
        token:
          description: Unique identifier of the refund.
          type: string
        type:
          $ref: '#/components/schemas/RefundType'
        updated_time:
          description: Date and time when the refund was last updated.
          format: date-time
          type: string
      required:
      - account_token
      - amount
      - created_time
      - currency_code
      - method
      - status
      - token
      - type
      - updated_time
      type: object
    RefundTransitionRequest:
      description: Request used to transition the status of a refund.
      properties:
        status:
          $ref: '#/components/schemas/RefundStatus'
        token:
          description: Unique identifier of the refund status transition.
          maxLength: 36
          type: string
      required:
      - status
      type: object
  securitySchemes:
    mqAppAndAccessToken:
      scheme: basic
      type: http