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

# Attaches an existing payment method to an account OR creates a brand new payment method and attaches it to an account

> Links an existing payment method to an account OR creates a new payment method and links it to an account, returns the payment methods linked to the account.



## OpenAPI

````yaml /marketONE/Amdocs_Media-Commerce-Gateway.yaml post /paymentMethod/account/{id}
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:
  /paymentMethod/account/{id}:
    post:
      tags:
        - paymentMethod
      summary: >-
        Attaches an existing payment method to an account OR creates a brand new
        payment method and attaches it to an account
      description: >-
        Links an existing payment method to an account OR creates a new payment
        method and links it to an account, returns the payment methods linked to
        the account.
      operationId: addAccountPaymentMethod
      parameters:
        - name: id
          in: path
          description: The SLM Account ID.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPaymentMethodRequestDTO'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model400Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model401Error'
        '404':
          description: 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
components:
  schemas:
    AddPaymentMethodRequestDTO:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: >
            Id of payment method. 

            If attaching an existing payment method to an account - must be an
            ID of an existing payment method;

            If creating a new payment method to be added to an account - a
            random value that will be used as the ID of the new payment method.
        vid:
          type: string
        primary:
          type: boolean
          description: >
            When creating/attaching a payment method without providing this
            attribute:

            - if there are no existing payment methods - it will become primary;

            - if at least one payment method already exists - it will become
            non-primary.
        active:
          type: boolean
          description: >-
            Indicates if the payment method is active. Must provide 'type'
            parameter if active=false.
          default: true
        type:
          type: string
          description: >-
            Type of payment method. Must be provided if attaching/creating an
            inactive payment method.
          enum:
            - CarrierBilling
            - ExternalBilling
            - MerchantAcceptedPayment
            - CreditCard
            - DebitCard
        merchantAcceptedPayment:
          $ref: '#/components/schemas/MerchantAcceptedPaymentRequest'
        creditCard:
          $ref: '#/components/schemas/CreditCardRequest'
        carrierBilling:
          $ref: '#/components/schemas/CarrierBillingRequest'
        debitCard:
          $ref: '#/components/schemas/DirectDebitRequest'
        externalBilling:
          $ref: '#/components/schemas/ExternalBillingRequest'
        currency:
          type: string
        policy:
          type: object
          additionalProperties:
            type: object
        metadata:
          $ref: '#/components/schemas/METADATA'
      description: >
        A request body to link an existing payment method to an account OR
        create a new payment method and link it to an account.

        When linking an existing payment method to an account:
          1. id - must be an id of an existing payment method to be linked to the account.
          2. Payment method object (merchantAcceptedPayment OR creditCard OR carrierBilling OR debitCard OR externalBilling based on the payment method type) - must be provided.
        When creating a new payment method and linking it to an account:
          1. id - a random value that will be used as the ID of the new payment method.
          2. Payment method object (merchantAcceptedPayment OR creditCard OR carrierBilling OR debitCard OR externalBilling based on the payment method type) - must NOT be provided.
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        metadata:
          $ref: '#/components/schemas/METADATA'
        paymentMethods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
    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
    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
    MerchantAcceptedPaymentRequest:
      type: object
      properties:
        amount:
          type: number
          description: >-
            Returns the payment amount for the payment method. Will be defaulted
            to zero when not provided.
        currency:
          type: string
          description: Currency for the payment method.
        created:
          type: string
          description: Created date and time.
        payment_type:
          type: string
          description: The identifier of the payment processor.
        account:
          type: string
          description: >-
            If applicable the account identifier of the customer that will be
            used for payment.
        last_digits:
          type: string
          description: Last 3 digits of the given account with obfuscation.
    CreditCardRequest:
      type: object
      properties:
        vid:
          $ref: '#/components/schemas/VID'
        account:
          type: string
          description: The masked credit card number
        bin:
          type: string
          description: bin
        last_digits:
          type: string
          description: The last 4 digits of the PAN (Bank Identifier Number).
        account_length:
          type: integer
          description: The number of digits in the PAN (Bank Identifier Number).
        account_hash:
          type: string
          description: >-
            A hash of the full PAN. Any non-numeric characters should be removed
            prior to hashing. If the account number is provided, this may be
            left blank and the hash will be calculated by Vindicia. The exact
            length and format of this string may depend upon the hash algorithm
            chosen.
        hash_type:
          type: string
          description: >-
            The algorithm used for hashing the account number. If this value is
            not provided we assume SHA1.
          enum:
            - sha1
            - md5
        expiration_date:
          type: string
          description: >-
            Expiration date of the credit card, formatted as YYYYMM. For
            example, July, 2028 represented as 202807.
        extended_card_attributes:
          type: object
          description: Additional credit card details returned from Payment Provider
        cvn:
          type: string
          description: >-
            CVV (Card Verification Value) or CVN (Card Verification Number)
            printed on the card.
        last_au_request_date:
          type: string
          description: Timestamp of the most recent Account Updater request.
        last_update_date:
          type: string
          description: Timestamp of the most recent credit card update.
        au_response_code:
          type: string
          description: >-
            Response code from the payment provider for the most recent Account
            Updater request.
        au_response_message:
          type: string
          description: >-
            Reply from the payment provider for the most recent Account Updater
            request.
    CarrierBillingRequest:
      type: object
      properties:
        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.
    DirectDebitRequest:
      type: object
      properties:
        account:
          type: string
          description: >-
            The number of the customer’s bank account from which to deduct
            payment.
        last_digits:
          type: string
          description: >-
            The last part of the account number for display purposes, generally
            the last four digits. If the account field is provided, this may be
            left blank and it will be filled in by Vindicia.
        account_length:
          type: integer
          description: >-
            Length of the total account number. If the full account number is
            submitted, this field may be left blank; Vindicia will calculate it.
        hash_type:
          type: string
          description: Can be sha1, md5
          enum:
            - sha1
            - md5
        account_hash:
          type: string
          description: >-
            A hash of the full account number. Any non-numeric characters should
            be removed prior to hashing. If the account number is provided, this
            may be left blank and the hash will be calculated by Vindicia. The
            exact length and format of this string may depend upon the hash
            algorithm chosen.
        country_code:
          type: string
          description: >-
            The ISO-3166-1 two-letter code for the country in which the related
            bank account is located. This code must match the country code
            specified in the PaymentMethod object’s billing address.
        bank_sort_code:
          type: string
          description: >-
            The European bank sort code that identifies the bank that houses the
            customer’s bank account whose number is specified in the account
            field. This code is similar to the bank routing number in the United
            States. Required You if this is for a Transaction processed through
            Subscribe unless the countryCode attribute is set to NL or BE.
        rib_code:
          type: string
          description: The RIB code for an DirectDebit account (France only)
        branch_code:
          type: string
          description: The branch code for an Direct Debit account
      description: This object defines Direct Debit details (vary by country/system)
    ExternalBillingRequest:
      type: object
      properties:
        bill_receiver:
          type: string
          description: >-
            The payment provider. In this case the payment provider is another
            billing system implemented in the integration.
        payment_channel:
          type: string
          description: >-
            The customer paymentChannelId in the billing system. Best practice
            is to set this the same as the Payment Method id.
        financial_account:
          type: string
          description: The customer financial account ID in the billing system.
    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.
    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
    Model400ValError:
      required:
        - code
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    VID:
      maxLength: 128
      type: string
      description: >-
        A Globally Unique Identifier (GUID) for this object. This value is
        generated by MarketONE.
    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.
    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
  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.