> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds a transaction

> Refunds a transaction. Note this does NOT cancel the subscription



## OpenAPI

````yaml /marketONE/Amdocs_Media-Commerce-Gateway.yaml post /transactions/refund
openapi: 3.0.1
info:
  title: ULM Storefront Gateway
  description: >
    These APIs allow clients to perform purchase and payment method management;
    OTT service and billing authorization operations. These APIs require a user
    access token. The APIs are thus aware of and therefore authorized by this
    ULM context (a user's entitlements as defined in the ULM platform service).


    <b>The following tracing headers can be used for all APIs:</b>


    X-B3-TraceId: The TraceId indicates the overall ID of the trace. Every span
    in a trace shares this ID. The X-B3-TraceId header is encoded as 32 or 16
    lower-hex characters. For example, a 128-bit TraceId header might look like
    463ac35c9f6413ad48485a3953bb6124.


    X-B3-SpanId: The SpanId is 64-bit in length and indicates the position of
    the current operation in the trace tree. The value should not be
    interpreted; it may or may not be derived from the value of the TraceId. The
    X-B3-SpanId header is encoded as 16 lower-hex characters. For example, a
    SpanId header might look like a2fb4a1d1a96d312. Unless propagating only the
    Sampling State, the X-B3-SpanId header is required.


    X-B3-ParentSpanId: The ParentSpanId is 64-bit in length and indicates the
    position of the parent operation in the trace tree. When the span is the
    root of the trace tree, there is no ParentSpanId. The X-B3-ParentSpanId
    header may be present on a child span and must be absent on the root span.
    It is encoded as 16 lower-hex characters. For example, a ParentSpanId header
    might look like 0020000000000001.


    <b>The APIs can be accessed via a tenant specific domain or the
    X-Aggregator-Code header must specify a MarketONE organization code:</b>


    X-Aggregator-Code: The aggregator organization code. Organization code must
    be provided either via HTTP header or query parameter. If both are provided,
    HTTP header will be used.


    aggregatorCode: The aggregator organization code. Organization code must be
    provided either via HTTP header or query parameter. If both are provided,
    HTTP header will be used.
  version: Latest
servers:
  - url: https://default.ulm.stg.m1amdocs.io/storefront
security:
  - bearerAuth: []
paths:
  /transactions/refund:
    post:
      tags:
        - transactions
      summary: Refunds a transaction
      description: Refunds a transaction. Note this does NOT cancel the subscription
      operationId: refundTransaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model400Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model401Error'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model403Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model404Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model500Error'
      security:
        - bearerAuth:
            - storefront-csr
            - m2m.storefront.csr.manage
components:
  schemas:
    RefundRequest:
      required:
        - transactionId
        - userId
      type: object
      properties:
        userId:
          $ref: '#/components/schemas/ID'
        transactionId:
          $ref: '#/components/schemas/ID'
        includeTax:
          type: boolean
          description: whether the amount is tax-inclusive or -exclusive
          default: true
        amount:
          type: number
          description: >-
            Amount of the refund. Must be positive (non-zero) and less than or
            equal to the as-yet-un-refunded balance of the specified
            transaction. Ignored if refundItems are specified.
    RefundResponse:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        amount:
          type: number
        taxIncluded:
          type: boolean
        transaction:
          $ref: '#/components/schemas/TransactionResponseDTO'
    Model400Error:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          enum:
            - invalid-request
        message:
          type: string
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/Model400ValError'
    Model401Error:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          enum:
            - authentication-required
            - invalid-api-key
            - api-key-not-found
        message:
          type: string
    Model403Error:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          enum:
            - forbidden
            - access-denied
            - invalid-scope
            - not-permitted
        message:
          type: string
    Model404Error:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          enum:
            - not-found
        message:
          type: string
    Model500Error:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          enum:
            - server-error
        message:
          type: string
    ID:
      maxLength: 256
      type: string
      description: A unique identifier.
    TransactionResponseDTO:
      type: object
      properties:
        transactionId:
          type: string
        createdDate:
          type: string
        amount:
          type: number
          description: >-
            The net amount of the charge presented by this transaction, as a
            decimal. Must be positive (zero allowed).
        currency:
          type: string
        status:
          type: string
        status_log:
          type: array
          description: >-
            A log of various TransactionStatus entries associated with this
            transaction.
          items:
            $ref: '#/components/schemas/TransactionStatus'
        subscriptionId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/TransactionItemResponseDTO'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
    Model400ValError:
      required:
        - code
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    TransactionStatus:
      type: object
      properties:
        object:
          type: string
          description: Value is “TransactionStatus”
          enum:
            - TransactionStatus
        status:
          type: string
          description: Status of the Transaction.
          enum:
            - New
            - AuthorizationPending
            - AuthorizedPending
            - Authorized
            - AuthorizedForValidation
            - Cancelled
            - Captured
            - Settled
            - Refunded
            - Pending
        created:
          type: string
          description: The effective datetime of this status
        payment_method_type:
          type: string
          description: Type of Payment Method (clarifies status).
          enum:
            - CreditCard
            - PayPal
            - ECP
            - DirectDebit
            - Token
            - HostedPage
            - Boleto
            - CSPAcceptedPayment
            - CarrierBilling
            - Amazon
            - Skrill
            - ApplePay
        vin_avs:
          type: string
          description: AVS result.
          enum:
            - FullMatch
            - PartialMatch
            - NoMatch
            - IssuerError
            - NoOpinion
            - NotSupported
        funding_source_balance:
          type: number
    TransactionItemResponseDTO:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        price:
          type: number
        quantity:
          type: number
        taxType:
          type: string
        discount:
          type: number
        subTotal:
          type: number
        total:
          type: number
        subscriptionItemId:
          type: string
        tax:
          type: array
          items:
            $ref: '#/components/schemas/TransactionItemTaxResponseDTO'
    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        createdDate:
          type: string
        merchantAcceptedPayment:
          $ref: '#/components/schemas/MerchantAcceptedPayment'
        creditCard:
          $ref: '#/components/schemas/CreditCard'
        carrierBilling:
          $ref: '#/components/schemas/CarrierBilling'
        debitCard:
          $ref: '#/components/schemas/DirectDebit'
        externalBilling:
          $ref: '#/components/schemas/ExternalBilling'
        metadata:
          $ref: '#/components/schemas/METADATA'
        primary:
          type: boolean
        active:
          type: boolean
        currency:
          type: string
        type:
          type: string
          description: Type of payment method.
          enum:
            - CarrierBilling
            - ExternalBilling
            - MerchantAcceptedPayment
            - CreditCard
            - DebitCard
    TransactionItemTaxResponseDTO:
      type: object
      properties:
        jurisdiction:
          type: string
          description: Tax jurisdiction
        name:
          type: string
          description: Tax description
        amount:
          type: number
          description: Currency amount of assessed tax
        externalTaxName:
          type: string
        externalTaxCategory:
          type: string
        externalJurisdictionName:
          type: string
        taxRate:
          type: number
      description: And individual tax assessed for a specified jurisdiction.
    MerchantAcceptedPayment:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
        created:
          type: string
        paymentType:
          type: string
        account:
          type: string
        lastDigits:
          type: string
    CreditCard:
      type: object
      properties:
        lastDigits:
          type: string
        expirationDate:
          type: string
    CarrierBilling:
      type: object
      properties:
        object:
          type: string
          description: Value is "CarrierBilling"
          enum:
            - CarrierBilling
        phone_number:
          $ref: '#/components/schemas/PhoneNumber'
        encoded_phone_number:
          type: string
          description: >-
            Read Only. The payment provider-encoded phone number used in the
            Transaction.
        carrier:
          type: string
          description: >-
            The identifier for the carrier, either read from the phone or
            entered by the customer.
        payment_provider:
          $ref: '#/components/schemas/PaymentProvider'
        currency:
          type: string
          description: >-
            ISO 4217 Currency Code for either the static_price_inc_salestax, or
            the dynamic_target_price. (For dynamic pricing, the customer
            currency will be determined by the customer region/countryCode.)
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 Country Code for the customer’s location.
        price_criteria:
          $ref: '#/components/schemas/PriceCriteria'
        account_identifier:
          maxLength: 255
          type: string
          description: Unique billing account identifier from Payment Provider BSS.
        carrier_billing_account_identifier_type:
          type: string
          description: the type of the account_identifier. Enumerated.
          example: MSISDN
          enum:
            - BAN
            - MSISDN
        customer_identifier:
          maxLength: 255
          type: string
          description: >
            Unique MSISDN or other billing account identifier from Payment
            Provider's BSS.
          example: not yet available - see VIN-26551
        customer_identifier_type:
          maxLength: 255
          type: string
          description: >
            Identifier for the channel from which the customer_identifier value
            originated
          example: PoS , Web
        validated:
          type: string
          description: Indicates if the payment method is validated
      description: This object defines Telco carrier billing details.
    DirectDebit:
      type: object
      properties:
        lastDigits:
          type: string
    ExternalBilling:
      type: object
      properties:
        billReceiver:
          type: string
        paymentChannel:
          type: string
        financialAccount:
          type: string
    METADATA:
      type: object
      additionalProperties:
        type: string
        properties:
          key:
            type: string
          value:
            type: string
      description: >-
        A set of key/value pairs that you can attach to an object. Useful for
        storing additional information.
    PhoneNumber:
      type: object
      properties:
        object:
          type: string
          description: Value is "PhoneNumber"
          enum:
            - PhoneNumber
        phone_type:
          type: string
          description: >-
            Type or Use designation for the phone number. Value can be CS, Fax,
            Home, Main, Mobile, Pager, Unspecified, Work
          enum:
            - CS
            - Fax
            - Home
            - Main
            - Mobile
            - Pager
            - Unspecified
            - Work
        country_code:
          type: string
          description: Country Code segment of a phone number.
        area_code:
          type: string
          description: Area Code segment of a phone number.
        local_number:
          type: string
          description: Local segment of a phone number (excluding extension).
        extension:
          type: string
          description: Phone number extension.
        raw_input:
          type: string
          description: Raw, unfiltered data input by customer.
      description: >-
        The payment providers object represents processor or payment channel
        used to transact a particular charge.
    PaymentProvider:
      type: object
      properties:
        object:
          type: string
          description: Value is "PaymentProvider"
          enum:
            - PaymentProvider
        name:
          type: string
          description: Provider Name
        dispute_address:
          type: string
          description: Contact address for written disputes.
        dispute_email:
          type: string
          description: Contact email for electronic disputes.
        dispute_uri:
          type: string
          description: Contact URL for online disputes.
        auth_expiration_days:
          type: integer
          description: Default expiration timing (days) for un-captured authorizations.
        auth_currency_override:
          type: string
          description: Currency override for Authorizations
        metadata:
          type: object
          description: >-
            A set of key/value pairs that you can attach to an object. Useful
            for storing additional information.
      description: >-
        The payment providers object represents processor or payment channel
        used to transact a particular charge.
    PriceCriteria:
      type: object
      properties:
        object:
          type: string
          description: Value is "PriceCriteria"
          enum:
            - PriceCriteria
        payment_provider:
          $ref: '#/components/schemas/PaymentProvider'
        currency:
          type: string
          description: >-
            ISO 4217 Currency Code for for either the static_price_inc_salestax,
            or the dynamic_target_price Overrides CarrierBilling.currency.
        country_code:
          type: string
          description: >-
            ISO 3166-1 alpha-2 countryCode for customer location. Overrides
            CarrierBilling.countryCode.
        price_point_deviation_policy:
          type: string
          description: >-
            The price deviation policy for dynamic price selection. Value can be
            HiOnly, HiPreferred, LowOnly, LowPreferred, NearestNoPreference
          enum:
            - HiOnly
            - HiPreferred
            - LowOnly
            - LowPreferred
            - NearestNoPreference
        dynamic_price_mode:
          type: string
          description: >-
            Specifies which price point element is matched by the dynamic
            pricing algorithm. Values can be PayoutGross, PayoutNet, Price
          enum:
            - PayoutGross
            - PayoutNet
            - Price
        merchant_service_identifier:
          type: string
          description: Service identifier for Payment Provider/Merchant.
        sub_merchant_identifier:
          type: string
          description: Optional identifier of sub-merchant associated with Transaction.
        description:
          type: string
          description: ''
        fwd_url:
          type: string
          description: >-
            Overrides both the successful transaction forward-to URL and the
            failed transaction forward-to URL.
        static_selection_row_ref:
          type: integer
          description: Row number identifier in the static product/service price matrix
        static_price_inc_sales_tax:
          type: string
          description: >-
            Price including tax (the actual amount the consumer will pay). Used
            with Transactions with static ‘exact match’ pricing.
        dynamic_deviation:
          type: integer
          description: >-
            The percent deviation (+/- 1000) from the target value that is
            acceptable as a price point selection.
        dynamic_match:
          type: integer
          description: >-
            The percent deviation (+/- 1000) from the target value that is
            classified as an exact match.
        dynamic_target_price:
          type: string
          description: Target price in the specified currency for dynamic pricing.
      description: Price Criteria details used with telco carrier billing payment methods.
  securitySchemes:
    bearerAuth:
      type: oauth2
      description: OAuth 2.0 Authentication
      flows:
        authorizationCode:
          authorizationUrl: /oidc/authorize
          tokenUrl: /oidc/token
          scopes:
            storefront: gives access to user api in storefront
            storefront-csr: gives access to some csr api in storefront
            m2m.storefront.csr.manage: Allows the machine to create and manage(CRUD)
            m2m.storefront.csr.read: Allows the machine to read data only

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.