Gnosis Pay PCI API

openapi: 3.2.0
info:
  title: User Service PCI API
  version: 0.0.0
servers:
- url: https://core.prod.gnosispay.com/user-api
  description: Production
  variables: {}
- url: https://core.sandbox.gnosispay.in/user-api
  description: Sandbox
  variables: {}
tags:
- name: PCI
paths:
  /pci/cards/{cardId}/challenge:
    get:
      operationId: PCI_getCardChallenge
      summary: Get PCI EIP-712 Challenge
      description: 'Issues a one-time EIP-712 challenge. The response is a complete typed-data

        object that can be passed directly to signTypedData (convert message.nonce

        to BigInt first). After signing, forward the hex signature as

        x-eip712-signature and the nonce as x-eip712-nonce on the subsequent PCI

        data request. The challenge expires after 5 minutes and can only be used

        once.'
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/uuid'
      - name: action
        in: query
        required: true
        description: 'The operation being authorized: ''view-details'' (card PAN/CVV),

          ''view-pin'' (read PIN), ''change-pin'' (set new PIN).'
        schema:
          $ref: '#/components/schemas/PciAction'
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PciChallengeResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - PCI
      security:
      - BearerAuth: []
      x-ogen-operation-group: PCI
  /pci/cards/{cardId}/details:
    get:
      operationId: PCI_getCardDetails
      summary: Get Card Details
      description: 'Returns the card PAN and CVV encrypted under a client-provided AES session

        key (expiration date in plaintext). The caller RSA-OAEP encrypts a one-time

        AES-256 session key with the PCI public key and passes it as `encryptedKey`;

        the EIP-712 signature over a prior `view-details` challenge is passed via the

        `x-eip712-signature` / `x-eip712-nonce` headers. Fetched from partner-api

        over HTTP.'
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/uuid'
      - name: encryptedKey
        in: query
        required: true
        description: Base64-encoded RSA-OAEP encrypted AES-256 session key.
        schema:
          type: string
        explode: false
      - name: keyId
        in: query
        required: true
        description: Id of the `encryptionKeys` entry that wrapped `encryptedKey`.
        schema:
          type: string
        explode: false
      - name: x-eip712-signature
        in: header
        required: true
        description: EIP-712 signature over the `view-details` challenge.
        schema:
          type: string
      - name: x-eip712-nonce
        in: header
        required: true
        description: Nonce of the challenge that was signed.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PciEncryptedCardDetailsResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - PCI
      security:
      - BearerAuth: []
      x-ogen-operation-group: PCI
  /pci/cards/{cardId}/pin:
    get:
      operationId: PCI_getCardPin
      summary: Get Card PIN
      description: 'Returns the card PIN encrypted under a client-provided AES session key. The

        caller RSA-OAEP encrypts a one-time AES-256 session key with the PCI public

        key and passes it as `encryptedKey`; the EIP-712 signature over a prior

        `view-pin` challenge is passed via the `x-eip712-signature` /

        `x-eip712-nonce` headers. Fetched from partner-api over HTTP.'
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/uuid'
      - name: encryptedKey
        in: query
        required: true
        description: Base64-encoded RSA-OAEP encrypted AES-256 session key.
        schema:
          type: string
        explode: false
      - name: keyId
        in: query
        required: true
        description: Id of the `encryptionKeys` entry that wrapped `encryptedKey`.
        schema:
          type: string
        explode: false
      - name: x-eip712-signature
        in: header
        required: true
        description: EIP-712 signature over the `view-pin` challenge.
        schema:
          type: string
      - name: x-eip712-nonce
        in: header
        required: true
        description: Nonce of the challenge that was signed.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PciEncryptedPinResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - PCI
      security:
      - BearerAuth: []
      x-ogen-operation-group: PCI
    post:
      operationId: PCI_setCardPin
      summary: Set Card PIN
      description: 'Sets the card PIN. The caller encrypts the new PIN (in PIN Block 2 format)

        with an AES session key, then RSA-OAEP encrypts the session key with the PCI

        public key. The EIP-712 signature over a prior `change-pin` challenge is

        passed via the `x-eip712-signature` / `x-eip712-nonce` headers. Proxied to

        partner-api over HTTP.'
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/uuid'
      - name: x-eip712-signature
        in: header
        required: true
        description: EIP-712 signature over the `change-pin` challenge.
        schema:
          type: string
      - name: x-eip712-nonce
        in: header
        required: true
        description: Nonce of the challenge that was signed.
        schema:
          type: string
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - PCI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PciSetEncryptedPinRequest'
      security:
      - BearerAuth: []
      x-ogen-operation-group: PCI
  /pci/public-key:
    get:
      operationId: PCI_getPublicKey
      summary: Get PCI Public Key
      description: 'Returns the RSA-OAEP SHA-256 public key (Base64-encoded DER SPKI) used to

        encrypt AES session keys, plus the same key in `encryptionKeys`. The client

        wraps a one-time AES-256 session key with that key and sends its id as

        `keyId`. The key is fetched from partner-api over HTTP.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PciPublicKeyResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - PCI
      security:
      - BearerAuth: []
      x-ogen-operation-group: PCI
components:
  schemas:
    PciChallengeMessage:
      type: object
      required:
      - authorization
      - nonce
      properties:
        authorization:
          type: string
          description: 'Human-readable action string, e.g. "Display VISA Card Details". This is

            what the user will see in their wallet.'
        nonce:
          type: string
          description: 'Random uint256 as a decimal string. Must be passed back as the

            x-eip712-nonce header alongside the signature.'
    NotFound:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    PciEncryptionKey:
      type: object
      required:
      - id
      - algorithm
      - publicKey
      properties:
        id:
          type: string
          description: Stable id the client sends back as `keyId` when it wraps with this key.
        algorithm:
          type: string
          description: OAEP algorithm this key expects. Clients match this when choosing a key.
        publicKey:
          type: string
          description: Base64-encoded DER (SPKI) RSA public key.
    PciChallengeResponse:
      type: object
      required:
      - domain
      - primaryType
      - types
      - message
      properties:
        domain:
          $ref: '#/components/schemas/PciChallengeDomain'
          description: EIP-712 domain separator.
        primaryType:
          type: string
          enum:
          - Message
          description: EIP-712 primary type.
        types:
          $ref: '#/components/schemas/PciChallengeTypes'
          description: EIP-712 type definitions.
        message:
          $ref: '#/components/schemas/PciChallengeMessage'
          description: EIP-712 message payload.
      description: 'Complete EIP-712 typed data. Pass this object directly to signTypedData —

        convert message.nonce to BigInt before signing.'
    PciChallengeDomain:
      type: object
      required:
      - name
      - version
      - chainId
      properties:
        name:
          type: string
        version:
          type: string
        chainId:
          type: integer
          format: int64
    PciAction:
      type: string
      enum:
      - view-details
      - view-pin
      - change-pin
      description: 'The operation being authorized: ''view-details'' (card PAN/CVV), ''view-pin''

        (read PIN), ''change-pin'' (set new PIN).'
    PciPublicKeyResponse:
      type: object
      required:
      - publicKey
      - encryptionKeys
      properties:
        publicKey:
          type: string
          description: 'Base64-encoded DER (SPKI) of the RSA-OAEP SHA-256 public key. This is the

            same key as the matching `encryptionKeys` entry. Clients wrap the session

            key with that entry and send its id as `keyId`.'
        encryptionKeys:
          type: array
          items:
            $ref: '#/components/schemas/PciEncryptionKey'
          description: 'RSA public keys a client may wrap a session key with. The client sends the

            chosen entry''s id back as `keyId`.'
    PciEncryptedPinResponse:
      type: object
      required:
      - encryptedPin
      - iv
      properties:
        encryptedPin:
          type: string
          description: AES-GCM encrypted PIN (PIN Block 2 format), Base64-encoded.
        iv:
          type: string
          description: Base64-encoded AES-GCM initialization vector.
    uuid:
      type: string
      format: uuid
    PciEncryptedCardDetailsResponse:
      type: object
      required:
      - cardNumber
      - cvv
      - expirationDate
      - iv
      properties:
        cardNumber:
          type: string
          description: AES-GCM encrypted card number (PAN), Base64-encoded.
        cvv:
          type: string
          description: AES-GCM encrypted CVV, Base64-encoded.
        expirationDate:
          type: string
          description: Card expiration date in plaintext (e.g. "12/28").
        iv:
          type: string
          description: Base64-encoded AES-GCM initialization vector.
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    Unauthorized:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    PciChallengeTypes:
      type: object
      required:
      - Message
      properties:
        Message:
          type: array
          items:
            $ref: '#/components/schemas/PciEip712Field'
    PciSetEncryptedPinRequest:
      type: object
      required:
      - encryptedKey
      - encryptedPin
      - iv
      - keyId
      properties:
        encryptedKey:
          type: string
          description: Base64-encoded RSA-OAEP encrypted AES-256 session key.
        encryptedPin:
          type: string
          description: AES-GCM encrypted PIN in PIN Block 2 format, Base64-encoded.
        iv:
          type: string
          description: Base64-encoded AES-GCM initialization vector.
        keyId:
          type: string
          description: Id of the `encryptionKeys` entry that wrapped `encryptedKey`.
    PciEip712Field:
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
        type:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer