CyberSource Credentials API

openapi: 3.2.0
info:
  description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
  version: 0.0.1
  title: CyberSource Merged Spec bankAccountValidation Credentials API
servers:
- url: https://apitest.cybersource.com/
tags:
- name: Credentials
  description: MPP (Machine Payment Protocol) token provisioning and encrypted credential generation. Use these APIs to provision encrypted payment credentials for use in MPP Authorization Payment headers. Accepts an instrument identifier and merchant challenge context, returns RSA-OAEP encrypted token payloads.
paths:
  /acp/v1/mpp/credentials:
    post:
      tags:
      - Credentials
      summary: Provision MPP credentials
      description: "Provisions an encrypted MPP credential for use as the credential payload in an Authorization: Payment header (MPP spec Section 8.2).\nThe caller provides an instrument identifier (referencing a stored card in TMS) and the challenge context from the merchant's 402 response, including the merchant's RSA public encryption key.\nThis service:\n  1. Calls TMS to retrieve the network token and cryptogram for the instrument.\n  2. Builds the token plaintext (MPP spec Section 8.3, type: network_token).\n  3. Encrypts the plaintext using RSA-OAEP with SHA-256 and the merchant's public key.\n  4. Returns the MPP credential payload fields (MPP spec Section 8.2, Table 4).\n"
      operationId: provisionMppCredentials
      x-devcenter-metaData:
        categoryTag: Machine_Payment_Protocol
        mleForRequest: mandatory
        mleForResponse: mandatory
        disableProcessorDropDown: true
        disableDefaultMerchantCreds: false
        authorizationType:
        - Json Web Token
        overrideMerchantCredential: agentic_mid_091225001
      responses:
        '200':
          description: OK
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: mppCredentialsResponse200
                type: object
                required:
                - token
                - network
                - lastFour
                - expirationMonth
                - expirationYear
                - dynamicData
                - eci
                - paymentAccountReference
                description: 'MPP payment credentials response. The ''token'' field Contains the RSA-OAEP encrypted network token ciphertext. All other fields are display-only metadata.

                  '
                properties:
                  token:
                    type: string
                    description: Base64-encoded RSA-OAEP encrypted token ciphertext. Must not be parsed by client/server — forwarded opaquely to the Server Enabler.
                  network:
                    type: string
                    description: "Card network.\nPossible values:\n  - `visa`\n  - `mastercard`\n  - `amex`\n  - `discover`\n"
                  lastFour:
                    type: string
                    minLength: 4
                    maxLength: 4
                    description: Last four digits of the card number as displayed to cardholder.
                  expirationMonth:
                    type: string
                    minLength: 2
                    maxLength: 2
                    description: Token expiration month (e.g., '06'). Display only.
                  expirationYear:
                    type: string
                    minLength: 4
                    maxLength: 4
                    description: Token expiration year, four digits (e.g., '2028'). Display only.
                  dynamicData:
                    type: string
                    description: Base64-encoded cryptogram from TSP. Present only for network_token type. Display only.
                  eci:
                    type: string
                    description: Electronic Commerce Indicator (e.g., '05', '07'). Present only for network_token type. Display only.
                  paymentAccountReference:
                    type: string
                    description: Payment Account Reference — a stable reference to the underlying funding account.
        '400':
          description: Bad Request
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: mppCredentialsBadRequestResponse400
                type: object
                properties:
                  error:
                    type: object
                    description: Error response object.
                    required:
                    - status
                    - reason
                    - message
                    properties:
                      status:
                        type: string
                        description: HTTP status code to categorize the errors.
                      reason:
                        type: string
                        description: Error reason as associated with the HTTP status code
                      message:
                        type: string
                        description: Error message as associated with the HTTP status code.
                      detail:
                        type: object
                        description: Additional details about the error.
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error.
                          source:
                            type: string
                            description: Source for the error
                          sourceType:
                            type: string
                            description: Detail about source for the error
                          message:
                            type: string
                            description: Detailed message for the error
        '401':
          description: Unauthorized
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: mppCredentialsUnauthorizedResponse401
                type: object
                properties:
                  error:
                    type: object
                    description: Error response object.
                    required:
                    - status
                    - reason
                    - message
                    properties:
                      status:
                        type: string
                        description: HTTP status code to categorize the errors.
                      reason:
                        type: string
                        description: Error reason as associated with the HTTP status code
                      message:
                        type: string
                        description: Error message as associated with the HTTP status code.
                      detail:
                        type: object
                        description: Additional details about the error.
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error.
                          source:
                            type: string
                            description: Source for the error
                          sourceType:
                            type: string
                            description: Detail about source for the error
                          message:
                            type: string
                            description: Detailed message for the error
        '403':
          description: Forbidden
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: mppCredentialsForbiddenResponse403
                type: object
                properties:
                  error:
                    type: object
                    description: Error response object.
                    required:
                    - status
                    - reason
                    - message
                    properties:
                      status:
                        type: string
                        description: HTTP status code to categorize the errors.
                      reason:
                        type: string
                        description: Error reason as associated with the HTTP status code
                      message:
                        type: string
                        description: Error message as associated with the HTTP status code.
                      detail:
                        type: object
                        description: Additional details about the error.
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error.
                          source:
                            type: string
                            description: Source for the error
                          sourceType:
                            type: string
                            description: Detail about source for the error
                          message:
                            type: string
                            description: Detailed message for the error
        '404':
          description: Not Found
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: mppCredentialsNotFoundResponse404
                type: object
                properties:
                  error:
                    type: object
                    description: Error response object.
                    required:
                    - status
                    - reason
                    - message
                    properties:
                      status:
                        type: string
                        description: HTTP status code to categorize the errors.
                      reason:
                        type: string
                        description: Error reason as associated with the HTTP status code
                      message:
                        type: string
                        description: Error message as associated with the HTTP status code.
                      detail:
                        type: object
                        description: Additional details about the error.
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error.
                          source:
                            type: string
                            description: Source for the error
                          sourceType:
                            type: string
                            description: Detail about source for the error
                          message:
                            type: string
                            description: Detailed message for the error
        '500':
          description: Internal Server Error
          content:
            application/hal+json;charset=utf-8:
              schema:
                title: mppCredentialsInternalServerErrorResponse500
                type: object
                properties:
                  error:
                    type: object
                    description: Error response object.
                    required:
                    - status
                    - reason
                    - message
                    properties:
                      status:
                        type: string
                        description: HTTP status code to categorize the errors.
                      reason:
                        type: string
                        description: Error reason as associated with the HTTP status code
                      message:
                        type: string
                        description: Error message as associated with the HTTP status code.
                      detail:
                        type: object
                        description: Additional details about the error.
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error.
                          source:
                            type: string
                            description: Source for the error
                          sourceType:
                            type: string
                            description: Detail about source for the error
                          message:
                            type: string
                            description: Detailed message for the error
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              required:
              - instrumentId
              - challenge
              type: object
              description: Request object for provisioning an MPP payment token.
              properties:
                instrumentId:
                  type: string
                  minLength: 1
                  description: TMS instrument identifier referencing the stored card.
                challenge:
                  required:
                  - id
                  - realm
                  - amount
                  - currency
                  - acceptedNetworks
                  - merchantId
                  - merchantName
                  - encryption_jwk
                  type: object
                  description: MPP challenge context received from the merchant's 402 response.
                  properties:
                    id:
                      type: string
                      minLength: 1
                      description: Unique challenge identifier issued by the merchant server.
                    realm:
                      type: string
                      minLength: 1
                      description: Merchant realm (typically the API domain).
                    amount:
                      type: string
                      minLength: 1
                      description: Amount in the smallest currency unit (e.g., '4999' = $49.99).
                    currency:
                      type: string
                      minLength: 3
                      maxLength: 3
                      description: Three-letter ISO 4217 currency code, lowercase (e.g., 'usd').
                    acceptedNetworks:
                      type: array
                      description: Card networks accepted by the merchant (e.g., ['visa', 'mastercard']).
                      items:
                        type: string
                    merchantId:
                      type: string
                      minLength: 1
                      description: Merchant identifier (maps to 'recipient' in MPP spec request object).
                    merchantName:
                      type: string
                      minLength: 1
                      description: Human-readable merchant name.
                    encryption_jwk:
                      required:
                      - kty
                      - kid
                      - use
                      - alg
                      - n
                      - e
                      type: object
                      description: Merchant RSA public encryption key as a JSON Web Key (JWK,  RFC 7517). Must be RSA (kty=RSA), alg=RSA-OAEP-256, use=enc. Used to encrypt the token payload using RSA-OAEP with SHA-256 per MPP spec Section 7.4.
                      properties:
                        kty:
                          type: string
                          minLength: 1
                          description: Key type. MUST be 'RSA'.
                        kid:
                          type: string
                          minLength: 1
                          description: Key ID. Identifies the key within a JWKS.
                        use:
                          type: string
                          minLength: 1
                          description: Public key use. MUST be 'enc'.
                        alg:
                          type: string
                          minLength: 1
                          description: Algorithm. MUST be 'RSA-OAEP-256'.
                        n:
                          type: string
                          minLength: 1
                          description: RSA modulus (Base64urlUInt-encoded per RFC 7518 Section 6.3.1.1).
                        e:
                          type: string
                          minLength: 1
                          description: RSA public exponent (Base64urlUInt-encoded per RFC 7518 Section 6.3.1.2).
              example:
                instrumentId: 459F91C888E1ED0EE063AF598E0AA44D
                challenge:
                  id: ch_9xK2mR4vB7nQ
                  realm: api.merchant.com
                  amount: '1200'
                  currency: USD
                  acceptedNetworks:
                  - visa
                  merchantId: merch_abc123
                  merchantName: acme_corp
                  encryption_jwk:
                    kty: RSA
                    kid: test-enc-key-01
                    use: enc
                    alg: RSA-OAEP-256
                    n: sEpiOr0VIbr20jGqJ0DUjdmbyhpr_kJ30e661yFv0z4epiPH1UEnAK4w6Ja9RDWZXY4usRYtAoFc3FihpOWEaAjjm6doqCQTn4Re2eiekeBtTZje6kZL7OZxoI3LGeInySfMzVYltySmEJIDyn_TF9npIQFcDItHVhhxDqkHuCI6MrWqQyyOXjacZaHUDcvhidyxRELlALWA_2xdGpR6kWknqqf0gQCWx-3jCfDoI3BQLUDdKDK700ptbuDT-ThCabGAw7TYJQu2lT1nIWpxzH-3kyvZwiCTYYsCh2lrv_aaO3gskKMqWZJBgJwjF0AVDc7mUOvttxibxz2LsnZDhQIDAQAB
                    e: AQAB
        required: true
x-devcenter-metaData:
  categoryTagArray:
  - name: Payments
    description: For more information about Payments transactions, see the [Payments Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html).
  - name: Transaction_Batches
    description: For more information about Transaction Batches, see the [Transaction Batches Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-transaction-batch-api/txn_batch_api_intro.html).
  - name: eCheck_AVS
    description: For more information about eCheck Account Validation, see the [Account Validation Developer Guides Page](https://...).
  - name: Token_Management
    description: For more information about the Token Management Service (TMS) see the [Token Management Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/all/rest/tms/tms-overview.html)
  - name: Flex_Microform
    description: Microform Integration is a lightweight acceptance solution designed to safely and securely accept payment information within your web page.  Microform is designed to a be embedded seamlessly within your existing webpage experience, blending in with your existing acceptance form.  This solution allows for the replacement of sensitive payment date with a transient token (a short lived reference to the sensitive payment data).  For more information about Flex Microform transactions, see the [Flex Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-flex/SAFlexibleToken.html). For examples on how to integrate Flex Microform within your webpage please see our [GitHub Flex Samples](https://github.com/CyberSource?q=flex&type=&language=)
  - name: Flex_API
    description: For more information about Flex API, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/da-flex-api-intro.html).
  - name: Risk_Management
  - name: Payouts
    description: 'For more information about Payouts, see the [Payouts Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-payouts/Introduction.html).

      '
  - name: Installments
    description: For more information about Installment contact Cybersource Support. For Visa installments contact VISthroughCYBS@visa.com
  - name: Recurring_Billing_Subscriptions
    description: For more information about Recurring Billing, see the [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-developer/recur-bill-services-intro.html).
  - name: BIN_Lookup
    description: 'The BIN Lookup Service is a versatile business tool that provides card network agnostic solution designed to ensure frictionless transaction experience by utilizing up-to-date Bank Identification Number (BIN) attributes sourced from multiple global and regional data sources.

      This service helps to improve authorization rates by helping to route transactions to the best-suited card network, minimizes fraud through card detail verification and aids in regulatory compliance by identifying card properties. The service is flexible and provides businesses with a flexible choice of inputs such as primary account number (PAN), network token from major networks (such as Visa, American Express, Discover and regional networks) which includes device PAN (DPAN), and all types of tokens generated via CyberSource Token Management Service (TMS).

      Currently, the range of available credentials is contingent on the networks enabled for the business entity. Therefore, the network information specified in this documentation is illustrative and subject to personalized offerings for each reseller or merchant.

      '
  - name: Transaction_Details
    description: For more information about Transaction Details, see the [Transaction Details Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_details_api.html).
  - name: Transaction_Search
    description: For more information about Transaction Search, see the [Transaction Search Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_search_api.html).
  - name: Reporting
    description: 'For more information about Reporting, see the [Reporting Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-reporting-rest-api-dev-guide-102718/reporting_api.html).

      '
  - name: Secure_File_Share
    description: For more information about Secure File Share, see the [Secure File Share Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-secure-file-share-api-102718/secure_file_share_api_intro.html).
  - name: Invoices
    description: For more information about Invoicing, see the [Invoicing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/Introduction.html).
  - name: Pay_By_Link
    description: For more information about PayByLink, see the [PBL Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/boarding/user/all/rest/boarding/templates-matrix-intro/templates-matrix-pay-by-link.html).
  - name: User_Management
    description: For more information about User Management, see the [User Managment Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-user-management-api-102718/user_management_api_intro.html).
  - name: Value_Added_Service
  - name: Fee Service
  - name: Merchant_Boarding
    description: For more information about Merchant Boarding, please see [Developer Guides Page](https://developer.cybersource.com/api/developer-guides/Merchant-Boarding-API_ditamap/Merchant-Boarding-API.html).
  - name: Webhooks
    description: For more information about Webhooks, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.html).
  - name: Unified_Checkout
    description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html).
  - name: Unified_Checkoutv1
    description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-about-guide.html).
  - name: Account_Updater
    description: For more information about Account Updater, see the [Account Updater Developer Guides Page:](https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html).
  - name: Visa_Bank_Account_Validation
    description: 'The Visa Bank Account Validation Service is a new standalone product designed to validate customer''s routing and bank account number combination for ACH transactions. Merchant''s can use this standalone product to validate their customer''s account prior to processing an ACH transaction against the customer''s account to comply with Nacha''s account validation mandate for Web-debit transactions.

      '
  - name: Currency Conversion
    description: 'Empower global transactions with transparency and choice. Our Dynamic Currency Conversion API lets merchants offer customers the option to pay in their home currency at checkout, delivering real-time exchange rates and clear cost disclosure.


      **Key Benefits:**

      - **Enhanced Customer Experience:** Provide clarity and convenience for international shoppers.

      - **Real-Time Rates:** Accurate currency conversion with all the data required for acquirers and their merchants to maintain compliance with card network rules.

      - **Seamless Integration:** Flexible API endpoints for rate lookup, authorization, and capture.

      - **Regulatory Compliance:** Provides the data required for acquirers and merchants to meet and maintain card scheme requirements for disclosure and consent.


      Ideal for merchants and payment partners seeking to boost trust and conversion in cross-border commerce.


      **Key Features:**

      - **Rate Lookup:** Retrieves the most up-to-date exchange rate for eligible cards before authorization.

      - **Currency Choice:** Enables the merchant to offer customers the option to select between the merchant''s local currency and their card''s billing currency.

      - **Compliance:** Ensures merchants have the data required to adhere to card network regulations; exchange rates, markups, etc.


      **Supported Scenarios:**

      - Dynamic Currency Conversion when cardholder''s billing currency differs from merchant''s pricing currency.

      - Merchant and acquirer must support the cardholder''s billing currency.


      **Core API Endpoints:**


      **Currency Conversion API**

      Returns eligibility and exchange rate details, including:

      - exchangeRate

      - marginRate

      - reconciliationId and Id (for subsequent payment requests)


      **Payment Authorization with DCC***

      POST /pts/v2/payments

      Required fields include:

      - orderInformation.amountDetails.currency

      - orderInformation.amountDetails.originalCurrency

      - orderInformation.amountDetails.originalAmount

      - orderInformation.amountDetails.exchangeRate

      - currencyConversion.indicator (e.g., 1 = Converted, 2 = Nonconvertible, 3 = Declined)


      **Capture with DCC***

      POST /pts/v2/payments/{id}/captures

      Maps from original authorization and includes original and converted amounts.


      **Refund with DCC***

      POST /pts/v2/captures/{id}/refunds

      Maps from original authorization and includes original and converted amounts.


      *Note: DCC is only supported on select processors. Contact your acquirer or account manager for more information.


      **Compliance & Disclosure:**


      Merchants must:

      - Adhere to card network rules for Dynamic Currency Conversion (DCC) transactions.

      - Display the converted amount, exchange rate, and markup percentage and other required disclosures.

      - Obtain explicit cardholder consent before applying DCC.

      - Work with your acquirer to obtain full set of compliance requirements.


      For more information, see the [Currency Conversion Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/currency-conversion/developer/all/rest/currency-conversion/cc-intro.html).

      '
  - name: Intelligent_Commerce_Connect
    description: For more information about Intelligent Commerce Cross Network Service API, please see [Developer Guides](https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-about-guide.html).