openapi: 3.0.3
info:
  title: Card Provider Server
  version: "1.0"
paths:
  /sell:
    post:
      operationId: postSell
      description: |
        Generates a secure binary payload for the nano in order to authorize the transaction.
        - We send on sell endpoint the quoteId. The partner should retrieve the quote data (amounts…) from this id.
        - The final source of Truth for the user is the binary payload you generate.
      requestBody:
        description: Info for generating payload
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SellRequest"
      responses:
        "200":
          description: Sell ID with flattened JWS. `https://www.rfc-editor.org/rfc/rfc7515#section-7.2.2`
          x-summary: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellResponse"
              example:
                sellId: "SELL-ID-165940"
                amount: "1.337"
                payinAddress: "0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48"
                createdAt: "2030-05-26T14:13:39"
                providerFees: "0.0001"
                referralFees: "0.0001"
                providerSig:
                  payload: "CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ=="
                  signature: "MEUCIBRm4PrdgRw0aBwRepuOGGRmR/YPcCoyKNJ7UDjFO030AiEA/VT0anolum0a3X/9lGPeovZHqzeDG9brcUB4zhYmwbs="
        "400":
          description: Deposit wallet not available.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorPayload"
              example:
                messageKey: NO_DEPOSIT_WALLET_ERROR
                message: Deposit wallet not available. (you can add any useful field as you want)
        "404":
          description: Not found error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorPayload"
              examples:
                CURRENCY_FROM_NOT_FOUND_ERROR:
                  summary: CURRENCY_FROM_NOT_FOUND_ERROR
                  value:
                    messageKey: CURRENCY_FROM_NOT_FOUND_ERROR
                    message: When the currency from is not found. (you can add any useful field as you want)
                CURRENCY_TO_NOT_FOUND_ERROR:
                  summary: CURRENCY_TO_NOT_FOUND_ERROR
                  value:
                    messageKey: CURRENCY_TO_NOT_FOUND_ERROR
                    message: When the currency to is not found. (you can add any useful field as you want)
                SELL_QUOTE_NOT_FOUND_ERROR:
                  summary: SELL_QUOTE_NOT_FOUND_ERROR
                  value:
                    messageKey: SELL_QUOTE_NOT_FOUND_ERROR
                    message: When the sell quote is not found. (you can add any useful field as you want)
        "451":
          description: When the user's IP address is in a restricted region.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorPayload"
              examples:
                REGION_RESTRICTED_ERROR:
                  summary: REGION_RESTRICTED_ERROR
                  value:
                    messageKey: REGION_RESTRICTED_ERROR
                    message: User's IP address is in a restricted region. (you can add any useful field as you want)
                CURRENCY_REGION_RESTRICTED_ERROR:
                  summary: CURRENCY_REGION_RESTRICTED_ERROR
                  value:
                    messageKey: CURRENCY_REGION_RESTRICTED_ERROR
                    message: One of the currencies is disabled in user's region. (you can add any useful field as you want)

  /transaction/{sellId}/status:
    post:
      operationId: statusUpdate
      description: Updates the status of a sell transaction.
      security:
        - defaultApiKey: [ ]
      parameters:
        - name: sellId
          in: path
          required: true
          schema:
            type: string
          example: 1234
      requestBody:
        description: Status update payload
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StatusUpdate"
      responses:
        "200":
          description: Status updated.
          x-summary: OK
        "404":
          description: Sell transaction not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorPayload"
              examples:
                SELL_TRANSACTION_NOT_FOUND_ERROR:
                  summary: SELL_TRANSACTION_NOT_FOUND_ERROR
                  value:
                    messageKey: SELL_TRANSACTION_NOT_FOUND_ERROR
                    message: Sell transaction not found. (you can add any useful field as you want)
    get:
      operationId: getStatusUpdate
      description: Get status of a sell transaction.
      parameters:
        - name: sellId
          in: path
          required: true
          schema:
            type: string
          example: 1234
      security:
        - defaultApiKey: [ ]
      responses:
        "200":
          description: Status of transaction returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorPayload"
        "404":
          description: Sell transaction not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorPayload"
              examples:
                SELL_TRANSACTION_NOT_FOUND_ERROR:
                  summary: SELL_TRANSACTION_NOT_FOUND_ERROR
                  value:
                    messageKey: SELL_TRANSACTION_NOT_FOUND_ERROR
                    message: Sell transaction not found. (you can add any useful field as you want)
components:
  securitySchemes:
    defaultApiKey:
      type: apiKey
      name: x-api-key
      in: header
  schemas:
    SellRequest:
      required:
        - quoteId
        - amount
        - refundAddress
        - fromCryptoCurrency
        - toFiatCurrency
        - payloadCryptoCurrency
        - nonce
      type: object
      properties:
        quoteId:
          type: string
          description: Previously generated quote ID.
        amount:
          type: string
          description: Amount requested by the user to be sold.
        refundAddress:
          type: string
          description: User's refund address, typically the fromAddress.
        fromCryptoCurrency:
          type: string
          description: From currency ID, using the provider's identifiers.
        toFiatCurrency:
          type: string
          description: Fiat currency at the ISO-4217 standard.
        payloadCryptoCurrency:
          type: string
          description: From currency ID, using Ledger's referential. (representing currency_from in the protobuf payload
        nonce:
          type: string
          description: Value for the `device_transaction_id_ng` field in the protobuf payload, in hex format of the byte array nonce received by the user.
        slippage:
          type: string
          description: Value between 0 to 1 (0.1 => 10%). Maximum difference between the quoted amount and the final amount received, as a ratio. If exceeded, user consent is required or a refund is made.

    SellResponse:
      required:
        - sellId
        - payinAddress
        - createdAt
        - providerFees
        - referralFees
        - providerSig
      type: object
      properties:
        sellId:
          type: string
          description: "provider's id of the ongoing sell transaction. This will be used by Ledger's backend to retrieve the status of user sell transaction. A unique id must be generated each time this endpoint is called, even if called with a same quoteId : quoteId != sellId. This is a sell attempt id and several retries sharing the same quote id might be performed by a user."
        payinAddress:
          type: string
          description: Provider's payin address.
        createdAt:
          type: string
          description: Creation date of the sell payload in ISO-8601 format.
        providerFees:
          type: string
          description: Fees paid to the provider, converted to currencyTo.
        referralFees:
          type: string
          description: Fees paid to Ledger, as a referral fee, converted to currencyTo.
        providerSig:
          $ref: "#/components/schemas/ProviderSig"
    ProviderSig:
      required:
        - payload
        - signature
      type: object
      properties:
        payload:
          type: string
          description: Protobuf payload (in binary format).
        signature:
          type: string
          description: Payload signed in JWS format.
    ErrorPayload:
      type: object
      required:
        - messageKey
        - message
      properties:
        messageKey:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message description.
        additionalFields:
          type: object
          description: Provides further details on the error, including specific amounts involved in the request. All amounts are presented in their respective currency units.
    StatusUpdate:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          enum:
            - FINISHED
            - EXPIRED
            - ON_HOLD
            - PENDING
            - TRANSFER_IN_COMPLETED
            - REFUNDED
            - UNKNOWN
        amount:
          type: string
          description: as soon as this information is known, this should contain the final amount transferred to the user in output currency.
        payinTransactionId:
          type: string
          description: as soon as this information is known, this should contain the payin transaction hash.
        providerFees:
          type: string
          description: Fees paid to the provider.
        referralFees:
          type: string
          description: Fees paid to Ledger, as a referral fee.

    StatusResponse:
      type: object
      properties:
        deviceStatus:
          type: string
          enum:
            - ACCEPTED
            - CANCELLED
          description: Status of the transaction from the user device
        providerStatus:
          type: string
          enum:
            - FINISHED
            - EXPIRED
            - ON_HOLD
            - PENDING
            - TRANSFER_IN_COMPLETED
            - REFUNDED
            - UNKNOWN
          description: Status of the transaction from the provider updates