openapi: 3.1.0
x-stoplight:
  id: 13kye2yiww6ci
info:
  title: TSP API for eCOM transactions
  version: '1.0'
servers:
  - url: 'https://TSP_PROD_DOMAIN/tsp/ecom'
    description: Production server
  - url: 'https://TSP_STAGING_DOMAIN/tsp/ecom'
    description: Staging server
paths:
  '/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/transactions':
    post:
      summary: 'POST /merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/transactions'
      operationId: createTransaction
      parameters:
        - $ref: '#/components/parameters/merchantGatewayId'
        - $ref: '#/components/parameters/merchantId'
        - $ref: '#/components/parameters/tokenId'
      tags:
        - Create Transaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createTransactionReq'
      responses:
        '200':
          description: Transaction Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createTransactionRes'
        '400':
          description: Error while performing the operation
          content:
            application/json:
              schema:
                type: object
                description: Error Information Response
                required:
                  - responseCode
                properties:
                  responseCode:
                    type: number
                    description: |
                      Error Response code to the request
                      |Error code | Description| Retryable|
                      |-------|-------|-------|
                      |111|Missing mandatory parameter|N|
                      |112|Bad parameter format|N|
                      |113|Unknown issuer|N|
                      |115|Unknown product|N|
                      |119|Unknown Token|N|
                      |163|Product not supported for mobile payment|N|
                      |164|FPAN Digitization Count Exceeded|N|
                      |166|Invalid FPAN|N|
                      |167|Card already enrolled|N|
                      |321|Operation on token already on-going|N|
                      |322|Time to live of the operation expired|N|
                      |431|Invalid perso data|N|
                      |432|Current token state does not allow this operation|N|
                      |911|Operation failed|N|
                      |921|Unexpected server error|Y|
                  errorMessage:
                    type: string
                    description: Textual error message
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-stoplight:
        id: gw2w3crc1jiib
components:
  schemas:
    createTransactionReq:
      type: object
      required:
        - transactionId
        - transactionDateTime
        - amount
        - currencyCode
      properties:
        transactionId:
          type: string
          pattern: '^[A-Za-z0-9]{1,12}$'
          example: Rrn123456789
        transactionDateTime:
          type: string
          pattern: '^[0-9]{14}$'
          description: UTC Transaction date in 'YYYYMMDDhhmmss' format.
          example: '20260225140530'
        amount:
          type: string
          pattern: '^[0-9]{12}$'
          description: smallest unit of currency right justified with leading zeros
          example: '000000002100'
        currencyCode:
          type: string
          description: Currency code as per ISO 4217
          pattern: '^[0-9]{3}$'
          example: '978'
    createTransactionRes:
      type: object
      properties:
        encryptedData:
          type: string
          description: |-
            The payment credentials data encrypted with JWE format (https://datatracker.ietf.org/doc/html/rfc7516) using following encryption parameters:<br/>
            * JWE base64url encoded string
            * "alg" (Algorithm) header parameter: ECDH-ES
            * "enc" (Encryption Algorithm) header parameter: A256GCM
            * "kid" (Key ID) header parameter: Key identifier corresponding to EC public key of the recipient
            * EC curve: P-256
            The JSON object that is encrypted is defined as follows:

            |JSON field parameter name|description|MOC|Length|
            |-------|-------|-------|-------|
            |dpan|The token PAN value|M|Up to 19|
            |exp|The token expiry date in the format MMYY|M|4|
            |cryptogram|The payment cryptogram to use with the token for a payment|M|Up to 256|

            **Example**: ```{"dpan:"9580981500100002", "exp":"1222", "cryptogram": "45f8grzty7f4f5gs5s2c"}```
  responses:
    '500':
      description: Internal Server Error - Not retryable
    '503':
      description: Unavailable - Retryable
  parameters:
    merchantGatewayId:
      name: merchantGatewayId
      in: path
      required: true
      schema:
        type: string
        description: Merchant Gateway Identifier.
        minLength: 10
        maxLength: 10
        example: MGW_123456
    merchantId:
      name: merchantId
      in: path
      required: true
      schema:
        type: string
        description: Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.
        minLength: 11
        maxLength: 11
        example: '10610027312'
    tokenId:
      name: tokenId
      in: path
      required: true
      schema:
        type: string
        maxLength: 48
        minLength: 1
        description: Unique Token Identifier
tags:
  - name: Create Transaction
