openapi: 3.0.0
info:
  title: Dime API Documentation - Card Routes
  description: >-
    This API supports various functionalities for cards within the Dime payment
    system.
  version: 1.0.0
servers:
  - url: https://api.dimepay.app/dapi/v1
    description: Production server
  - url: https://sandbox.api.dimepay.app/dapi/v1
    description: Sandbox server for testing
paths:
  /cards:
    post:
      summary: Create a new card
      operationId: createApiCard
      parameters:
        - name: client_key
          in: header
          required: true
          schema:
            type: string
            example: abcd1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                lang:
                  type: string
                  description: The language that should be used
                  example: en
                data:
                  type: string
                  description: >-
                    A signed JWT containing the card input details. **Fields to
                    include in the JWT payload:**


                    - `currency`: The currency of the card (e.g., USD).

                    - `cardholder_first_name`: First name of the cardholder.

                    - `cardholder_last_name`: Last name of the cardholder.

                    - `cardholder_email`: Email address of the cardholder.

                    - `card_number`: Card number in plain format (e.g.,
                    `5100270000000023`).

                    - `card_cvv`: CVV of the card (e.g., `123`).

                    - `card_expiry`: Expiry date of the card (MMYY format).

                    - `card_address`: Billing address of the card.

                    - `card_city`: City of the billing address.

                    - `card_country`: Country of the billing address.

                    - `card_postal_code`: Postal code of the billing address.


                    **Example of unsigned payload:**

                    ```json

                    {
                      "currency": "USD",
                      "cardholder_first_name": "John",
                      "cardholder_last_name": "Doe",
                      "cardholder_email": "john.doe@example.com",
                      "card_number": "5100270000000023",
                      "card_cvv": "123",
                      "card_expiry": "1225",
                      "card_address": "123 Main Street",
                      "card_city": "New York",
                      "card_country": "US",
                      "card_postal_code": "10001"
                    }

                    ```

                    **Example of signing the payload:**

                    ```javascript

                    const jwt = require('jsonwebtoken');

                    const payload = { /* fields above */ };

                    const signedData = jwt.sign(payload, 'your_secret_key');

                    ```


                    **Final request payload:**

                    ```json

                    {
                      "lang": "en",
                      "data": "<signed_jwt_token>"
                    }

                    ```
                  example: >-
                    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeSI6IlVTRCIsImNhcmRob2xkZXJfZmlyc3RfbmFtZSI6IkpvaG4iLCJjYXJkaG9sZGVyX2xhc3RfbmFtZSI6IkRvZSIsImNhcmRob2xkZXJfZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsImNhcmRfbnVtYmVyIjoiNTEwMDI3MDAwMDAwMDIzIiwiY2FyZF9jdnYiOiIxMjMiLCJjYXJkX2V4cGlyeSI6IjEyMjUiLCJjYXJkX2FkZHJlc3MiOiIxMjMgTWFpbiBTdHJlZXQiLCJjYXJkX2NpdHkiOiJOZXcgWW9yayIsImNhcmRfY291bnRyeSI6IlVTIiwiY2FyZF9wb3N0YWxfY29kZSI6IjEwMDAxIn0.qT0a8IHtdI-fUVTZAFnLMx79rmmbAtR0h4G9GhT2nmM
              required:
                - lang
                - data
      responses:
        '201':
          description: Card created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardRequest'
  /cards/verify:
    post:
      summary: Verify a card
      operationId: verifyApiCard
      parameters:
        - name: client_key
          in: header
          required: true
          schema:
            type: string
            example: abcd1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                lang:
                  type: string
                  description: The language that should be used
                  example: en
                data:
                  type: string
                  description: >-
                    A signed JWT containing the card verification input details.
                    **Fields to include in the JWT payload:**


                    - `card_request_id`: Unique identifier for the card request.

                    - `value`: The verification value.


                    **Example of unsigned payload:**

                    ```json

                    {
                      "card_request_id": "550e8400-e29b-41d4-a716-446655440000",
                      "value": 10.25
                    }

                    ```

                    **Example of signing the payload:**

                    ```javascript

                    const jwt = require('jsonwebtoken');

                    const payload = { /* fields above */ };

                    const signedData = jwt.sign(payload, 'your_secret_key');

                    ```


                    **Final request payload:**

                    ```json

                    {
                      "lang": "en",
                      "data": "<signed_jwt_token>"
                    }

                    ```
                  example: >-
                    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkX3JlcXVlc3RfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJ2YWx1ZSI6MTAuMjV9.JkLNdq8kgMyslN_nupGnEzXrBMmu2_hAaiGpMe42-AE
              required:
                - lang
                - data
      responses:
        '200':
          description: Card verification successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/{token}:
    get:
      summary: Get card details
      operationId: getApiCard
      parameters:
        - name: client_key
          in: header
          required: true
          schema:
            type: string
            example: abcd1234
        - name: token
          in: path
          required: true
          schema:
            type: string
            description: >-
              A signed JWT containing the card token. **Fields to include in the
              JWT payload:**


              - `token`: The card's unique token.


              **Example of unsigned payload:**

              ```json

              {
                "token": "card_123abc456xyz"
              }

              ```

              **Example of signing the payload:**

              ```javascript

              const jwt = require('jsonwebtoken');

              const payload = { token: 'card_123abc456xyz' };

              const signedData = jwt.sign(payload, 'your_secret_key');

              ```


              **Final request URL:**

              `/cards/card_123abc456xyz?data=<signed_jwt_token>`
            example: >-
              eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6ImNhcmRfMTIzYWJjNDU2eHl6In0.7W3ISpqFnINqpm6QX-8oOn-d5M6ixJHiTTk6W0U_e94
          description: Unique token for the card
      responses:
        '200':
          description: Card details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
components:
  schemas:
    CardInput:
      type: object
      properties:
        currency:
          type: string
          enum:
            - USD
            - JMD
            - GBP
            - EUR
            - TTD
            - BBD
            - XCD
          description: The currency associated with the card
          example: USD
        cardholder_first_name:
          type: string
          description: The first name of the cardholder
          example: John
        cardholder_last_name:
          type: string
          description: The last name of the cardholder
          example: Doe
        cardholder_email:
          type: string
          format: email
          description: The email address of the cardholder
          example: john.doe@example.com
        card_number:
          type: string
          description: The number of the card in 5100270000000023 format
          example: '5100270000000023'
        card_cvv:
          type: string
          description: The cvv of the card in 123 format
          example: '123'
        card_expiry:
          type: string
          description: The expiration date of the card in MMYY format
          example: '1225'
        card_address:
          type: string
          description: The billing address of the card
          example: 123 Main Street
        card_city:
          type: string
          description: The city of the billing address
          example: New York
        card_country:
          type: string
          description: The country of the billing address
          example: US
        card_postal_code:
          type: string
          description: The postal code of the billing address
          example: '10001'
      required:
        - currency
        - cardholder_first_name
        - cardholder_last_name
        - cardholder_email
        - card_expiry
        - card_address
        - card_city
        - card_country
        - card_postal_code
    CardRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the card request
          example: 550e8400-e29b-41d4-a716-446655440000
        expired:
          type: boolean
          description: Indicates whether the card request is expired
          example: false
        status:
          type: string
          enum:
            - STARTED
            - VERIFICATION
            - FAILED
            - SUCCESS
          description: The current status of the card request
          example: SUCCESS
        currency:
          type: string
          enum:
            - USD
            - JMD
            - GBP
            - EUR
            - TTD
            - BBD
            - XCD
          description: The currency associated with the card request
          example: USD
        cardholder_name:
          type: string
          description: The full name of the cardholder
          example: John Doe
        cardholder_first_name:
          type: string
          description: The first name of the cardholder
          example: John
        cardholder_last_name:
          type: string
          description: The last name of the cardholder
          example: Doe
        cardholder_email:
          type: string
          format: email
          description: The email address of the cardholder
          example: john.doe@example.com
        card_expiry:
          type: string
          description: The expiration date of the card in MM/YY format
          example: 12/25
        card_type:
          type: string
          description: The type of the card (e.g., Credit, Debit)
          example: Credit
        card_scheme:
          type: string
          description: The scheme of the card (e.g., Visa, Mastercard)
          example: Visa
        card_address:
          type: string
          description: The billing address of the card
          example: 123 Main Street
        card_city:
          type: string
          description: The city of the billing address
          example: New York
        card_country:
          type: string
          description: The country of the billing address
          example: US
        card_postal_code:
          type: string
          description: The postal code of the billing address
          example: '10001'
        card_bank:
          type: string
          description: The bank associated with the card
          example: Bank of America
          nullable: true
        last_four_digits:
          type: string
          description: The last four digits of the card number
          example: '1234'
        metadata:
          type: object
          additionalProperties: true
          description: Optional metadata for the card request
      required:
        - id
        - expired
        - status
        - currency
        - cardholder_name
        - cardholder_first_name
        - cardholder_last_name
        - cardholder_email
        - card_expiry
        - card_type
        - card_scheme
        - card_address
        - card_city
        - card_country
        - card_postal_code
        - last_four_digits
    Card:
      type: object
      properties:
        entity_id:
          type: string
          format: uuid
          description: Unique identifier for the entity associated with the card
          example: 550e8400-e29b-41d4-a716-446655440000
          readOnly: true
        entity_type:
          type: string
          enum:
            - MERCHANT
            - PERSONAL
          description: Type of the entity associated with the card
          example: MERCHANT
          readOnly: true
        token:
          type: string
          description: Unique token for the card
          example: card_abcd12345
        card_token:
          type: string
          description: Token representing the card
          example: tok_abcdef12345
        currency:
          type: string
          enum:
            - USD
            - JMD
            - GBP
            - EUR
            - TTD
            - BBD
            - XCD
          description: Currency associated with the card
          example: USD
        cardholder_name:
          type: string
          description: Full name of the cardholder
          example: John Doe
        cardholder_first_name:
          type: string
          description: First name of the cardholder
          example: John
        cardholder_last_name:
          type: string
          description: Last name of the cardholder
          example: Doe
        cardholder_email:
          type: string
          format: email
          description: Email address of the cardholder
          example: john.doe@example.com
        card_expiry:
          type: string
          description: Expiration date of the card in MM/YY format
          example: 12/25
        card_scheme:
          type: string
          description: Scheme of the card (e.g., Visa, Mastercard)
          example: Visa
        card_address:
          type: string
          description: Billing address of the card
          example: 123 Main Street
        card_city:
          type: string
          description: City of the billing address
          example: New York
        card_country:
          type: string
          description: Country of the billing address
          example: US
        card_postal_code:
          type: string
          description: Postal code of the billing address
          example: '10001'
        card_bank:
          type: string
          description: Bank associated with the card
          example: Bank of America
          nullable: true
        last_four_digits:
          type: string
          description: Last four digits of the card number
          example: '1234'
        metadata:
          type: object
          additionalProperties: true
          description: Optional metadata for the card
        card_type:
          type: string
          description: Type of the card (e.g., Credit, Debit)
          example: Credit
        token_expiration_date:
          type: string
          format: date-time
          description: Expiration date of the card token
          example: '2025-12-31T23:59:59Z'
      required:
        - entity_id
        - entity_type
        - token
        - card_token
        - currency
        - cardholder_name
        - cardholder_first_name
        - cardholder_last_name
        - cardholder_email
        - card_expiry
        - card_scheme
        - card_address
        - card_city
        - card_country
        - card_postal_code
        - last_four_digits
        - card_type
        - token_expiration_date
    CardVerificationInput:
      type: object
      properties:
        card_request_id:
          type: string
          format: uuid
          description: Unique identifier for the card request
          example: 550e8400-e29b-41d4-a716-446655440000
        value:
          type: number
          format: double
          description: Verification value for the card request
          example: 10.25
          readOnly: true
      required:
        - card_request_id
        - value
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: client_key
      in: header
security:
  - ApiKeyAuth: []
