Weavr Cards API

openapi: 3.2.0
info:
  title: Weavr Simulator Cards API
  x-logo:
    url: https://storage.googleapis.com/weavr-cdn/weavr_logo-new.png
    backgroundColor: '#FFFFFF'
    altText: Weavr
  description: This is a Simulator API which is only available on the Weavr Sandbox Environment
  contact:
    name: Weavr
    url: http://weavr.io
  version: v2
servers:
- url: https://sandbox.weavr.io/simulate/api"
tags:
- name: Cards
paths:
  /cards/{card_id}/expire:
    post:
      tags:
      - Cards
      summary: Simulate expiry of card
      description: Expire a managed card by Card ID. Provide card id and the card will be expired.
      operationId: cards_card_id_expire
      parameters:
      - name: card_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/call-ref'
      responses:
        '204':
          description: Success - No Content
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpireManagedCardConflict'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
  /cards/{card_id}/about_to_expire:
    post:
      tags:
      - Cards
      summary: Simulate card about to expire
      description: Simulate a card about to expire by Card ID. Provide card id and the card will be set to about to expire.
      operationId: cards_card_id_about_to_expire
      parameters:
      - name: card_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/call-ref'
      responses:
        '204':
          description: Success - No Content
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
  /cards/{card_id}/purchase:
    post:
      tags:
      - Cards
      summary: Simulate card purchase using card id
      description: Simulate card purchases by Card ID. Provide card id and transaction amount and the transaction will be processed through the system.
      operationId: cards_card_id_purchase
      parameters:
      - name: card_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/call-ref'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequestByCardId'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
  /cards/{card_id}/renew:
    post:
      tags:
      - Cards
      summary: Simulate renewal of card
      description: Renew a managed card by Card ID. Provide card id and the card will be renewed.
      operationId: cards_card_id_renew
      parameters:
      - name: card_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/call-ref'
      responses:
        '204':
          description: Success - No Content
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewManagedCardConflict'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
  /cards/{card_id}/merchant_refund:
    post:
      tags:
      - Cards
      summary: Simulate card merchant refund using card id
      description: Simulate card merchant refunds by Card ID. Provide card id and transaction amount and the transaction will be processed through the system.
      operationId: cards_card_id_merchant_refund
      parameters:
      - name: card_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/call-ref'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequestByCardId'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
  /cards/purchase:
    post:
      tags:
      - Cards
      summary: Simulate card purchase using card number
      description: Simulate card purchases. Provide card details and transaction amount and the transaction will be processed through the system.
      operationId: cards_purchase
      parameters:
      - $ref: '#/components/parameters/call-ref'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
  /cards/merchant_refund:
    post:
      tags:
      - Cards
      summary: Simulate card merchant refund using card number
      description: Simulate card merchant refunds. Provide card details and transaction amount and the transaction will be processed through the system.
      operationId: cards_merchant_refund
      parameters:
      - $ref: '#/components/parameters/call-ref'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvalidRequest'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
      security:
      - API_Secret_Key: []
components:
  schemas:
    PurchaseRequestByCardId:
      required:
      - merchantName
      - transactionAmount
      type: object
      properties:
        merchantName:
          maxLength: 50
          minLength: 1
          type: string
          description: The merchant name
          x-fieldValidation: required size(1,50)
        merchantId:
          maxLength: 15
          minLength: 1
          type: string
          description: The merchant id (MID). If not specified, a random value will be used
          x-fieldValidation: size(1,15)
        merchantCategoryCode:
          maxLength: 4
          minLength: 1
          type: string
          description: The merchant category code (MCC). If unspecified or an invalid MCC is specified, the Merchant Code 5399 (Misc. General Merchandise) will be used instead
          x-fieldValidation: size(1,4)
        transactionAmount:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
          - description: The amount of the purchase
            x-fieldValidation: required
        transactionCountry:
          maxLength: 3
          minLength: 3
          pattern: ^[A-Z]*$
          type: string
          description: The transaction country in ISO 3166 - alpha-3 format
          x-fieldValidation: size(3,3) regex([A-Z]*)
        forexFee:
          type: integer
          description: If this is a cross-currency transaction, the forex fee amount in the card currency. Deprecated; the forex fee percentage configured at the card profile will be applied if this field is not provided
          format: int64
          deprecated: true
        forexPadding:
          type: integer
          description: If this is a cross-currency transaction, the forex padding amount in the card currency. Deprecated; a 2% forex padding will be applied if this field is not provided
          format: int64
          deprecated: true
        atmWithdrawal:
          type: boolean
          description: If set to true, this purchase simulates and ATM Withdrawal transaction. MCC will automatically be set to 6011
        additionalMerchantData:
          allOf:
          - $ref: '#/components/schemas/AdditionalMerchantData'
          - description: Additional merchant data
        cardHolderPresent:
          allOf:
          - $ref: '#/components/schemas/CardHolderPresent'
          - description: Optional detail indicating if the card holder was present when the authorisation occurred.
        cardPresent:
          type: boolean
          description: Optional detail indicating if the card was present when the authorisation occurred.
        initiateBiometricThreeDSecure:
          type: boolean
          description: If the card is enrolled for Biometric Authentication, a 3DS Flow is initiated before the Purchase can resume.
        transactionTimestamp:
          type: integer
          description: Epoch timestamp using millisecond precision.
          format: int64
    CurrencyAmount:
      required:
      - currency
      type: object
      properties:
        currency:
          maxLength: 3
          minLength: 3
          pattern: ^[A-Z]*$
          type: string
          description: The currency ISO-4217 code, i.e. a three letter uppercase code, such as GBP, EUR, USD.
          x-fieldValidation: required size(3,3) regex([A-Z]*)
        amount:
          type: integer
          description: The monetary amount, scaled to the lowest denomination of the currency. For example, an amount of 1000 for a EUR currency is actually 1000 Euro cents, i.e. EUR 10.00.
          format: int64
      description: A message representing a monetary amount in a particular currency.
    PurchaseRequest:
      required:
      - cardNumber
      - cvv
      - expiryDate
      - merchantName
      - transactionAmount
      type: object
      properties:
        cardNumber:
          maxLength: 50
          minLength: 16
          pattern: ^[0-9 ]*$
          type: string
          description: The 16-digit card number.
          x-fieldValidation: required has_text size(16,50) regex(^[0-9 ]*$)
        cvv:
          type: string
          description: The 3-digit cvv
          x-fieldValidation: required has_text
        expiryDate:
          type: string
          description: The expiry date in format MMYY
          x-fieldValidation: required has_text
        merchantName:
          maxLength: 50
          minLength: 1
          type: string
          description: The merchant name
          x-fieldValidation: required size(1,50)
        merchantId:
          maxLength: 15
          minLength: 1
          type: string
          description: The merchant id (MID). If not specified, a random value will be used
          x-fieldValidation: size(1,15)
        merchantCategoryCode:
          maxLength: 4
          minLength: 1
          type: string
          description: The merchant category code (MCC). If unspecified or an invalid MCC is specified, the Merchant Code 5399 (Misc. General Merchandise) will be used instead
          x-fieldValidation: size(1,4)
        transactionAmount:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
          - description: The amount of the purchase
            x-fieldValidation: required
        forexFee:
          type: integer
          description: If this is a cross-currency transaction, the forex fee amount in the card currency. Deprecated; the forex fee percentage configured at the card profile will be applied if this field is not provided
          format: int64
          deprecated: true
        forexPadding:
          type: integer
          description: If this is a cross-currency transaction, the forex padding amount in the card currency. Deprecated; a 2% forex padding will be applied if this field is not provided. Deprecated; a 2% forex padding will be applied if this field is not provided
          format: int64
          deprecated: true
        atmWithdrawal:
          type: boolean
          description: If set to true, this purchase simulates and ATM Withdrawal transaction. MCC will automatically be set to 6011
        additionalMerchantData:
          allOf:
          - $ref: '#/components/schemas/AdditionalMerchantData'
          - description: Additional merchant data
        cardHolderPresent:
          allOf:
          - $ref: '#/components/schemas/CardHolderPresent'
          - description: Optional detail indicating if the card holder was present when the authorisation occurred.
        cardPresent:
          type: boolean
          description: Optional detail indicating if the card was present when the authorisation occurred.
        initiateBiometricThreeDSecure:
          type: boolean
          description: If the card is enrolled for Biometric Authentication, a 3DS Flow is initiated before the Purchase can resume.
        transactionTimestamp:
          type: integer
          description: Epoch timestamp using millisecond precision.
          format: int64
    ExpireManagedCardConflict:
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/ExpireManagedCardConflictErrorCode'
    FieldValidationType:
      type: string
      enum:
      - REQUIRED
      - HAS_TEXT
      - REQUIRES
      - SIZE
      - RANGE
      - IN
      - NOT_IN
      - REGEX
      - EXACTLY
      - AT_LEAST
      - AT_MOST
      - ALL_OR_NONE
    DefaultError:
      type: object
      properties:
        message:
          maxLength: 255
          type: string
          description: When present helps to identify and fix the problem.
          x-fieldValidation: size(_,255)
      description: A default error model in case of errors other than 400, 409 or 504.
    FieldValidationErrors:
      type: object
      properties:
        name:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidation'
    FieldValidation:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FieldValidationType'
        params:
          type: array
          items:
            type: string
    NullableInt64:
      type: object
      properties:
        value:
          type: integer
          description: If value is 0, set has_value to true
          format: int64
        hasValue:
          type: boolean
          description: If value is default (0) then true indicates 0 while false indicates null
    AdditionalMerchantData:
      type: object
      properties:
        merchantStreet:
          type: string
        merchantCity:
          type: string
        merchantState:
          type: string
        merchantPostalCode:
          type: string
        merchantCountry:
          maxLength: 3
          minLength: 3
          pattern: ^[A-Z]*$
          type: string
          x-fieldValidation: size(3,3) regex([A-Z]*)
        merchantTelephone:
          type: string
        merchantURL:
          type: string
        merchantNameOther:
          type: string
        merchantNetworkId:
          type: string
        merchantContact:
          type: string
    RenewManagedCardConflict:
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/RenewManagedCardConflictErrorCode'
    ExpireManagedCardConflictErrorCode:
      type: string
      enum:
      - INSTRUMENT_DESTROYED
      - INSTRUMENT_NOT_EXPIRABLE
      - TRANSACTION_BATCH_EXCEPTION
    PurchaseResponsePurchaseResponseCode:
      type: string
      enum:
      - APPROVED
      - DENIED_NOT_ENOUGH_FUNDS
      - DENIED_CARD_NOT_FOUND
      - DENIED_INCORRECT_CVV
      - DENIED_CARD_EXPIRY
      - DENIED_AMOUNT_NOT_POSITIVE
      - DENIED_CARD_INACTIVE
      - DENIED_OTHER
      - DENIED_SPEND_CONTROL
      - PENDING_BIOMETRIC_THREEDS_VERIFICATION
      - CARD_NOT_ENROLLED_FOR_BIOMETRIC_THREEDS
    MessageValidation:
      type: object
      properties:
        invalid:
          type: boolean
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationErrors'
    ClientInvalidRequest:
      type: object
      properties:
        message:
          maxLength: 255
          type: string
          description: When present helps to identify and fix the problem.
          x-fieldValidation: size(_,255)
        validation:
          allOf:
          - $ref: '#/components/schemas/MessageValidation'
          - description: Description of fields which were invalid.
    RenewManagedCardConflictErrorCode:
      type: string
      enum:
      - INSTRUMENT_DESTROYED
      - INSTRUMENT_MARKED_LOST_STOLEN
      - INSTRUMENT_NOT_RENEWABLE
      - TRANSACTION_BATCH_EXCEPTION
    CardHolderPresent:
      type: string
      enum:
      - PRESENT
      - NOT_PRESENT
      - PRESENCE_UNKNOWN
    PurchaseResponse:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/PurchaseResponsePurchaseResponseCode'
        threeDSecureChallengeId:
          $ref: '#/components/schemas/NullableInt64'
  parameters:
    call-ref:
      name: call-ref
      in: header
      description: A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255
      required: false
      style: simple
      explode: false
      schema:
        type: string
  securitySchemes:
    API_Secret_Key:
      type: apiKey
      description: The API Secret Key - available from the Configuration area of the Innovator Portal
      name: programme-key
      in: header
    Auth_Token:
      type: http
      description: 'Authorization Token returned by login - example format: e6YrWi53lW0Bb6TbBL4ADA=='
      scheme: bearer
      bearerFormat: JWT