openapi: 3.2.0
info:
  title: Silverflow Transaction Risk Assessment API
  version: 1.417.0
  contact:
    name: API Support
    email: support@silverflow.com
  license:
    name: Commercial
  description: 'Operations tagged Transaction Risk Assessment across 2 of this provider''s published API definitions: silverflow-openapi.yml, silverflow-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://eu-west-1.api.silverflow.com/v1
  description: Production URL for Europe - Equivalent to https://api.silverflow.co/v1
- url: https://us-east-2.api.silverflow.com/v1
  description: Production URL for North America
- url: https://eu-west-1.api-sbx.silverflow.com/v1
  description: Sandbox URL - Equivalent to https://api-sbx.silverflow.co/v1
security:
- ApiKey: []
- BearerToken: []
tags:
- name: Transaction Risk Assessment
  description: Transaction Risk Assessment
paths:
  /riskAssessments:
    post:
      operationId: performRiskAssessment
      summary: Perform a risk assessment for a given provider
      description: 'This endpoint is used to do a risk assessment outside of the transaction flow. It returns a risk assessment, along with a response from the given provider.


        Requires the `riskAsessments:Create` permission.

        '
      tags:
      - Transaction Risk Assessment
      requestBody:
        description: 'The POST body needs to have all the necessary information required to do a risk assessment.

          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskAssessmentRequest'
            examples:
              FraudioRequest:
                $ref: '#/components/examples/perform-risk-assessment-fraudio'
              CybersourceRequest:
                $ref: '#/components/examples/perform-risk-assessment-cybersource'
      responses:
        '201':
          headers:
            Location:
              description: The URL of the risk assessment
              schema:
                type: string
          description: Risk assessment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskAssessmentResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openapi_components-schemas-InvalidInputErrorDetails'
              examples:
                InvalidInputErrorExample:
                  $ref: '#/components/examples/components-examples-InvalidInputErrorExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas-NotAuthorizedErrorDetails'
        '408':
          description: Provider timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskProviderTimeoutError'
        '409':
          description: No customer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskProviderNoCustomerTokenError'
        '422':
          description: The server was unable to process the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantAcceptorNotFoundError'
        '500':
          description: Risk provider unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskProviderUnexpectedError'
    servers:
    - url: https://eu-west-1.api.silverflow.com/v1
      description: Production URL for Europe - Equivalent to https://api.silverflow.co/v1
    - url: https://us-east-2.api.silverflow.com/v1
      description: Production URL for North America
    - url: https://eu-west-1.api-sbx.silverflow.com/v1
      description: Sandbox URL - Equivalent to https://api-sbx.silverflow.co/v1
components:
  schemas:
    score:
      type: number
      description: The score of the Fraudio risk assessment.
      example: 0.533506949459276
    AcceptorKey:
      description: Uniquely identifies a Merchant Acceptor.
      type: string
      pattern: ^mac-[a-zA-Z0-9]+$
      example: mac-1JRadf2ffdfrdPMf2XrS2
    cybersourceId:
      type: string
      description: The id of the Cybersource risk assessment.
      example: '5526663169230178269497'
    Authentication:
      description: Details related to authentication of the transaction
      type: object
      properties:
        cvc:
          $ref: '#/components/schemas/CvcResult'
        avs:
          $ref: '#/components/schemas/AvsResult'
        threeDsResult:
          $ref: '#/components/schemas/ThreeDsResult'
    cybersourceProvider:
      type: string
      description: Indicator that risk assessment has been done with Cybersource.
      enum:
      - cybersource
    components-schemas-version:
      type: integer
      description: The version of this object
      format: int64
      readOnly: true
    openapi_components-schemas-city-2:
      type: string
      minLength: 1
      description: 'The city of the address.

        '
    CybersourceRequest:
      type: object
      additionalProperties: false
      required:
      - provider
      - merchantAcceptorKey
      - card
      - amount
      - chargeType
      - customer
      properties:
        provider:
          $ref: '#/components/schemas/cybersourceProvider'
        merchantAcceptorKey:
          $ref: '#/components/schemas/AcceptorKey'
        card:
          $ref: '#/components/schemas/components-schemas-CardInput'
        amount:
          $ref: '#/components/schemas/openapi_components-schemas-Amount-3'
        chargeType:
          $ref: '#/components/schemas/openapi_components-schemas-ChargeType-2'
        customer:
          $ref: '#/components/schemas/CybersourceCustomer'
        localTransactionDateTime:
          $ref: '#/components/schemas/schemas-LocalTransactionDateTime'
        authentication:
          $ref: '#/components/schemas/Authentication'
        authorizationFields:
          $ref: '#/components/schemas/Authorization'
    errorTitle:
      type: string
      description: 'A short, human-readable summary of the problem type. It does not change from occurrence to occurrence of the error.

        '
    openapi_components-schemas-InvalidInputErrorDetails:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      - validationErrors
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/errorType'
          - enum:
            - /silverflow/problems/invalid-input
        title:
          allOf:
          - $ref: '#/components/schemas/errorTitle'
          - enum:
            - Invalid Input
        status:
          allOf:
          - $ref: '#/components/schemas/errorStatus'
          - enum:
            - 400
        detail:
          $ref: '#/components/schemas/errorDetail'
        instance:
          $ref: '#/components/schemas/errorInstance'
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: A list of validation errors.
    schemas-amountValue:
      type: integer
      format: int64
      minimum: 0
      maximum: 900000000
      description: 'The amount in minor units. For example `$12.34` should be encoded as `1234`. Note that not all

        currencies have 2 minor units. Some have three or zero.

        '
    openapi_components-schemas-currencyCode-6:
      type: string
      pattern: ^[A-Z]{3}$
      description: An alphabetic ISO-4217 currency code.
      externalDocs:
        description: Find more info here
        url: https://www.iso.org/iso-4217-currency-codes.html
      example: EUR
    schemas-NotAuthorizedErrorDetails:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/errorType'
          - enum:
            - /silverflow/problems/riskAssessments/not-authorized
        title:
          allOf:
          - $ref: '#/components/schemas/errorTitle'
          - enum:
            - Not authorized
        status:
          allOf:
          - $ref: '#/components/schemas/errorStatus'
          - enum:
            - 401
        detail:
          $ref: '#/components/schemas/errorDetail'
        instance:
          $ref: '#/components/schemas/errorInstance'
    AvsResult:
      enum:
      - none
      - match
      - partial-match
      - no-match
      - not-processed
      description: The result of the AVS verification.
    expiryYear:
      type: integer
      description: 'The year the card expires including the century

        '
      minimum: 2020
      maximum: 2050
    openapi_components-schemas-pan-3:
      type: string
      writeOnly: true
      description: Full digits of a card
      pattern: ^\d{12,19}$
      format: password
      example: '1234123412341234'
    FraudioRequest:
      description: Fields used for a Fraudio request.
      required:
      - provider
      - merchantAcceptorKey
      - card
      - amount
      - chargeType
      type: object
      additionalProperties: false
      properties:
        provider:
          $ref: '#/components/schemas/fraudioProvider'
        merchantAcceptorKey:
          $ref: '#/components/schemas/AcceptorKey'
        card:
          $ref: '#/components/schemas/components-schemas-CardInput'
        amount:
          $ref: '#/components/schemas/openapi_components-schemas-Amount-3'
        chargeType:
          $ref: '#/components/schemas/openapi_components-schemas-ChargeType-2'
        customer:
          $ref: '#/components/schemas/FraudioCustomer'
        localTransactionDateTime:
          $ref: '#/components/schemas/schemas-LocalTransactionDateTime'
        authentication:
          $ref: '#/components/schemas/Authentication'
        authorizationFields:
          $ref: '#/components/schemas/Authorization'
    components-schemas-eci:
      type: string
      description: E-commerce Indicator
    openapi_components-schemas-AcceptorRef:
      type: object
      description: Reference key and status of the acceptor
      required:
      - key
      - version
      properties:
        key:
          $ref: '#/components/schemas/AcceptorKey'
        version:
          $ref: '#/components/schemas/components-schemas-version'
    intent:
      description: 'The intention of the cardholder.

        '
      type: string
      enum:
      - purchase
      - reservation
      - account-status
      - payout
      - payout-status
      - funding
      - advice
      - refund
    components-schemas-NameOfPeopleAndPlaces:
      type: string
      pattern: ^[\w -,\.\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]+$
      minLength: 1
      maxLength: 120
      example: Name
    errorInstance:
      type: string
      description: 'A reference that identifies the specific occurrence of the error. The instance is unique for every error.

        '
    ChargeKey:
      description: Uniquely identifies a charge.
      type: string
      pattern: ^chg-[a-zA-Z0-9]+$
      minLength: 5
      maxLength: 120
      example: chg-1e1dAHhgstYTUhlphPzZ
    CybersourceCustomer:
      type: object
      additionalProperties: false
      description: Details of the customer carrying out the transaction
      required:
      - firstName
      - lastName
      - email
      - phoneNumber
      - billingAddress
      properties:
        firstName:
          description: The first name of the customer.
          allOf:
          - $ref: '#/components/schemas/components-schemas-NameOfPeopleAndPlaces'
        lastName:
          description: The last name of the customer.
          allOf:
          - $ref: '#/components/schemas/components-schemas-NameOfPeopleAndPlaces'
        email:
          description: The email of the customer.
          allOf:
          - $ref: '#/components/schemas/email'
        phoneNumber:
          description: The phone number of the customer.
          allOf:
          - $ref: '#/components/schemas/schemas-phoneNumber'
        billingAddress:
          description: The billing address of the customer.
          $ref: '#/components/schemas/AddressInputAlpha2'
    components-schemas-order:
      description: 'The method used to place the order.

        '
      type: string
      enum:
      - checkout
      - unspecified
      - mail
      - phone
      - one-click
      - recurring
      - ucof
      - installment
      - counter
    openapi_components-schemas-Amount-3:
      type: object
      required:
      - value
      - currency
      additionalProperties: false
      description: 'An amount encoded as an object with a `value` in minor units and a `currency` code.

        '
      properties:
        value:
          $ref: '#/components/schemas/schemas-amountValue'
        currency:
          $ref: '#/components/schemas/openapi_components-schemas-currencyCode-6'
    errorStatus:
      type: integer
      format: int32
      description: 'The HTTP status code generated by the origin server for this occurrence

        of the problem.

        '
    openapi_components-schemas-cardEntry-2:
      description: 'The method used to capture the card details.

        '
      type: string
      enum:
      - e-commerce
      - manual
      - card-on-file
      - token
      - token-on-file
      - terminal
      example: e-commerce
    Authorization:
      description: The authorization fields received in the ISO response message.
      type: object
      properties:
        responseCode:
          $ref: '#/components/schemas/responseCode'
        eci:
          $ref: '#/components/schemas/components-schemas-eci'
    schemas-LocalTransactionDateTime:
      type: string
      format: date-time
      description: Date and time of the transaction in the local timezone.
    cybersource_score:
      type: integer
      description: The score of the Cybersource risk assessment.
      example: 10
    RiskProviderTimeoutError:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/errorType'
          - enum:
            - /silverflow/problems/riskAssessments/provider-timeout
        title:
          allOf:
          - $ref: '#/components/schemas/errorTitle'
          - enum:
            - Request timed out
        status:
          allOf:
          - $ref: '#/components/schemas/errorStatus'
          - enum:
            - 408
        detail:
          $ref: '#/components/schemas/errorDetail'
        instance:
          $ref: '#/components/schemas/errorInstance'
    RiskAssessmentKey:
      description: Uniquely identifies a risk assessment.
      type: string
      pattern: ^rak-[a-zA-Z0-9]+$
      minLength: 5
      maxLength: 120
      example: rak-1e1dAHhgstYTUhlphPzZ
    Provider:
      type: string
      description: The supported risk assessment providers.
      oneOf:
      - $ref: '#/components/schemas/fraudioProvider'
      - $ref: '#/components/schemas/cybersourceProvider'
    expiryMonth:
      type: integer
      description: 'The month the card expires. January is 1

        '
      minimum: 1
      maximum: 12
    openapi_components-schemas-status:
      type: string
      description: The status associated with the Cybersource risk assessment.
      enum:
      - ACCEPTED
      - REJECTED
      - PENDING_REVIEW
      - DECLINED
      - PENDING_AUTHENTICATION
      - INVALID_REQUEST
      - AUTHENTICATION_FAILED
      - CHALLENGE
    email:
      type: string
      description: A valid email address
      pattern: \w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*
    CybersourceResult:
      type: object
      additionalProperties: false
      required:
      - id
      - score
      - status
      description: A risk assessment result from Cybersource.
      properties:
        id:
          $ref: '#/components/schemas/cybersourceId'
        score:
          $ref: '#/components/schemas/cybersource_score'
        status:
          $ref: '#/components/schemas/openapi_components-schemas-status'
    RiskAssessmentRequest:
      oneOf:
      - $ref: '#/components/schemas/FraudioRequest'
      - $ref: '#/components/schemas/CybersourceRequest'
    fraudioProvider:
      type: string
      description: Indicator that risk assessment has been done with Fraudio.
      enum:
      - fraudio
    recommendation:
      description: The recommendation of the Fraudio risk assessment.
      type: string
      enum:
      - green
      - amber
      - red
      example: green
    errorDetail:
      type: string
      description: 'A human readable explanation specific to this occurrence of the problem.

        '
    openapi_components-schemas-terminalEntryMode:
      description: 'Required when `cardEntry` is `terminal`. This field indicates the method used for PAN entry on the terminal to initiate the transaction.

        '
      type: string
      enum:
      - contactless
      - chip
    responseCode:
      type: string
      description: Contents of field 39
    RiskAssessmentResult:
      type: object
      additionalProperties: false
      required:
      - key
      - provider
      - merchantAcceptorRef
      - card
      - amount
      - chargeType
      - result
      - created
      - status
      - version
      description: The risk assessment response.
      properties:
        key:
          $ref: '#/components/schemas/RiskAssessmentKey'
        provider:
          $ref: '#/components/schemas/Provider'
        merchantAcceptorRef:
          $ref: '#/components/schemas/openapi_components-schemas-AcceptorRef'
        chargeKey:
          $ref: '#/components/schemas/ChargeKey'
        card:
          $ref: '#/components/schemas/schemas-OutputCard'
        amount:
          $ref: '#/components/schemas/openapi_components-schemas-Amount-3'
        chargeType:
          $ref: '#/components/schemas/openapi_components-schemas-ChargeType-2'
        localTransactionDateTime:
          $ref: '#/components/schemas/schemas-LocalTransactionDateTime'
        customer:
          oneOf:
          - $ref: '#/components/schemas/FraudioCustomer'
          - $ref: '#/components/schemas/CybersourceCustomer'
        authentication:
          $ref: '#/components/schemas/Authentication'
        authorizationFields:
          $ref: '#/components/schemas/Authorization'
        result:
          oneOf:
          - $ref: '#/components/schemas/schemas-FraudioResult'
          - $ref: '#/components/schemas/CybersourceResult'
        created:
          $ref: '#/components/schemas/openapi_components-schemas-created-2'
        lastModified:
          $ref: '#/components/schemas/openapi_components-schemas-lastModified'
        status:
          $ref: '#/components/schemas/common_status'
        version:
          $ref: '#/components/schemas/components-schemas-version'
    openapi_components-schemas-countryCodeAlpha2:
      type: string
      pattern: ^[A-Z]{2}$
      description: 'The ISO code of the country.


        **European ISO Country Codes**


        <details>


        | Country | Alpha-2 code | Numeric |

        | ------- | ------------ | ------- |

        | Åland Islands | AX | 248 |

        | Andorra | AD | 020 |

        | Austria | AT | 040 |

        | Belgium | BE | 056 |

        | Cyprus | CY | 196 |

        | Estonia | EE | 233 |  |

        | Finland | FI | 246 |

        | France | FR | 250 |

        | French Guiana | GF | 254 |

        | French Southern Territories | TF | 260 |

        | Germany | DE | 280 |

        | Greece | GR | 300 |

        | Guadeloupe | GP | 312 |

        | Ireland | IE | 372 |

        | Italy | IT | 380 |

        | Kosovo, United Nations Mission in Kosovo (UNMIK) | QZ | 900 |

        | Latvia | LV | 428 |

        | Lithuania | LT | 440 |

        | Luxembourg | LU | 442 |

        | Malta | MT | 470 |

        | Martinique | MQ | 474 |

        | Mayotte | YT | 175 |

        | Monaco | MC | 492 |

        | Montenegro | ME | 499 |

        | Netherlands | NL | 528 |

        | Portugal | PT | 620 |

        | Reunion | RE | 638 |

        | Saint Barthélemy | BL | 652 |

        | Saint Martin (French Part) | MF | 663 |

        | San Marino | SM | 674 |

        | Slovakia | SK | 703 |

        | Slovenia | SI | 705 |

        | Spain | ES | 724 |

        | St. Pierre and Miquelon | PM | 666 |

        | Vatican City State (Holy See) | VA | 336 |


        </details>


        **US ISO Country Codes**


        <details>


        | Country | Alpha-2 code | Numeric |

        | ------- | ------------ | ------- |

        | American Samoa | AS | 016 |

        | Bonaire, St. Eusasius and Saba | BQ | 535 |

        | British Indian Ocean Territory | IO | 086 |

        | Ecuador | EC | 218 |

        | Guam | GU | 316 |

        | Marshall Islands | MH | 584 |

        | Micronesia, Federated States of | FM | 583 |

        | Northern Mariana Islands | MP | 580 |

        | Palau | PW | 585 |

        | Palestine, State of | PS | 275 |

        | Puerto Rico | PR | 630 |

        | Timor-Leste | TP | 626 |

        | Turks and Caicos Islands | TC | 796 |

        | U.S. Minor Outlying Islands | UM | 581 |

        | United States | US | 840 |

        | Virgin Islands, British | VG | 092 |

        | Virgin Islands, U.S. | VI | 850 |


        </details>


        **Other ISO Country Codes**


        <details>


        | Country | Alpha-2 code | Numeric |

        | ------- | ------------ | ------- |

        | Afghanistan | AF | 004 |

        | Albania | AL | 008 |

        | Algeria | DZ | 012 |

        | Angola | AO | 024 |

        | Anguilla | AI | 660 |

        | Antarctica | AQ | 010 |

        | Antigua and Barbuda | AG | 028 |

        | Argentina | AR | 032 |

        | Armenia | AM | 051 |

        | Aruba | AW | 533 |

        | Australia | AU | 036 |

        | Azerbaijan | AZ | 031 |

        | Bahamas | BS | 044 |

        | Bahrain | BH | 048 |

        | Bangladesh | BD | 050 |

        | Barbados | BB | 052 |

        | Belarus | BR | 112 |

        | Belize | BZ | 084 |

        | Benin | BJ | 204 |

        | Bermuda | BM | 060 |

        | Bhutan | BT | 064 |

        | Bolivia, Plurinational State of | BO | 068 |

        | Bosnia and Herzegovina | BA | 070 |

        | Botswana | BW | 072 |

        | Bouvet Island | BV | 074 |

        | Brazil | BR | 076 |

        | Brunei Darussalam | BN | 096 |

        | Bulgaria | BG | 100 |

        | Burkina Faso | BF | 854 |

        | Burundi | BI | 108 |

        | Cambodia | KH | 116 |

        | Cameroon | CM | 120 |

        | Canada | CA | 124 |

        | Cape Verde | CV | 132 |

        | Cayman Islands | KY | 136 |

        | Central African Republic | CF | 140 |

        | Chad | TD | 148 |

        | Chile | CL | 152 |

        | China | CN | 156 |

        | Christmas Island | CX | 162 |

        | Cocos (Keeling) Islands | CC | 166 |

        | Colombia | CO | 170 |

        | Comoros | KM | 174 |

        | Congo | CG | 178 |

        | Cook Islands | CK | 184 |

        | Costa Rica | CR | 188 |

        | Côte D''Ivoire | CI | 384 |

        | Croatia | HR | 191 |

        | Cuba | CU | 192 |

        | Curacao | CW | 531 |

        | Czech Republic | CZ | 203 |

        | Democratic Republic of the Congo | CD | 180 |

        | Denmark | DK | 208 |

        | Djibouti | DJ | 262 |

        | Dominica | DM | 212 |

        | Dominican Republic | DO | 214 |

        | Egypt | EG | 818 |

        | El Salvador | SV | 222 |

        | Equatorial Guinea | GQ | 226 |

        | Eritrea | ER | 232 |

        | Ethiopia | ET | 230 |

        | Falkland Islands (Malvinas) | FK | 238 |

        | Faroe Islands | FO | 234 |

        | Fiji | FJ | 242 |

        | French Polynesia | PF | 258 |

        | Gabon | GA | 266 |

        | Gambia | GM | 270 |

        | Georgia | GE | 268 |

        | Ghana | GH | 288 |

        | Gibraltar | GI | 292 |

        | Greenland | GL | 304 |

        | Grenada | GD | 308 |

        | Guatemala | GT | 320 |

        | Guernsey | GG | 831 |

        | Guinea | GN | 324 |

        | Guinea-Bissau | GW | 624 |

        | Guyana | GY | 328 |

        | Haiti | HT | 332 |

        | Heard and McDonald Islands | HM | 334 |

        | Honduras | HN | 340 |

        | Hong Kong | HK | 344 |

        | Hungary | HU | 348 |

        | Iceland | IS | 352 |

        | India | IN | 356 |

        | Indonesia | ID | 360 |

        | Iraq | IQ | 368 |

        | Isle of Man | IM | 833 |

        | Israel | IL | 376 |

        | Jamaica | JM | 388 |

        | Japan | JP | 392 |

        | Jersey | JE | 832 |

        | Jordan | JO | 400 |

        | Kazakhstan | KZ | 398 |

        | Kenya | KE | 404 |

        | Kiribati | KI | 296 |

        | Korea, Republic of | KR | 410 |

        | Kuwait | KW | 414 |

        | Kyrgyzstan | KG | 417 |

        | Lao People''s Democratic Republic | LA | 418 |

        | Lebanon | LB | 422 |

        | Lesotho | LS | 426 |

        | Liberia | LR | 430 |

        | Libyan Arab Jamahiriya | LY | 434 |

        | Liechtenstein | LI | 438 |

        | Macao | MO | 446 |

        | Macedonia | MK | 807 |

        | Madagascar | MG | 450 |

        | Malawi | MW | 454 |

        | Malaysia | MY | 458 |

        | Maldives | MV | 462 |

        | Mali | ML | 466 |

        | Mauritania | MR | 478 |

        | Mauritius | MU | 480 |

        | Mexico | MX | 484 |

        | Moldova, Republic of | MD | 498 |

        | Mongolia | MN | 496 |

        | Montserrat | MS | 500 |

        | Morocco | MA | 504 |

        | Mozambique | MZ | 508 |

        | Myanmar (effective 1 November 2012) | MM | 104 |

        | Namibia | NA | 516 |

        | Nauru | NR | 520 |

        | Nepal | NP | 524 |

        | Netherlands Antilles | AN | 530 |

        | New Caledonia | NC | 540 |

        | New Zealand | NZ | 554 |

        | Nicaragua | NI | 558 |

        | Niger | NE | 562 |

        | Nigeria | NG | 566 |

        | Niue | NU | 570 |

        | Norfolk Island | NF | 574 |

        | Norway | NO | 578 |

        | Oman | OM | 512 |

        | Pakistan | PK | 586 |

        | Panama | PA | 591 |

        | Papua New Guinea | PG | 598 |

        | Paraguay | PY | 600 |

        | Peru | PE | 604 |

        | Philippines | PH | 608 |

        | Pitcairn | PN | 612 |

        | Poland | PL | 616 |

        | Qatar | QA | 634 |

        | Republic of South Sudan | SS | 728 |

        | Romania | RO | 642 |

        | Russian Federation | RU | 643 |

        | Rwanda | RW | 646 |

        | Samoa | WS | 882 |

        | Sao Tome and Principe | ST | 678 |

        | Saudi Arabia | SA | 682 |

        | Senegal | SN | 686 |

        | Serbia | RS | 688 |

        | Seychelles | SC | 690 |

        | Sierra Leone | SL | 694 |

        | Singapore | SG | 702 |

        | Sint Maarten (Dutch Part) | SX | 534 |

        | Solomon Islands | SB | 090 |

        | Somalia | SO | 706 |

        | South Africa | ZA | 710 |

        | South Georgia and the South Sandwich Islands | GS | 239 |

        | Sri Lanka | LK | 144 |

        | Saint Helena, Ascension and Tristan Da Cunha | SH | 654 |

        | St. Kitts and Nevis | KN | 659 |

        | St. Lucia | LC | 662 |

        | St. Vincent and the Grenadines | VC | 670 |

        | Suriname | SR | 740 |

        | Svalbard and Jan Mayen | SJ | 744 |

        | Swaziland | SZ | 748 |

        | Sweden | SE | 752 |

        | Switzerland | CH | 756 |

        | Taiwan | TW | 158 |

        | Tajikistan | TJ | 762 |

        | Tanzania, United Republic of | TZ | 834 |

        | Thailand | TH | 764 |

        | Togo | TG | 768 |

        | Tokelau | TK | 772 |

        | Tonga | TO | 776 |

        | Trinidad and Tobago | TT | 780 |

        | Tunisia | TN | 788 |

        | Turkey | TR | 792 |

        | Turkmenistan | TM | 795 |

        | Tuvalu | TV | 798 |

        | Uganda | UG | 800 |

        | Ukraine | UA | 804 |

        | United Arab Emirates | AE | 784 |

        | United Kingdom | GB | 826 |

        | Uruguay | UY | 858 |

        | Uzbekistan | UZ | 860 |

        | Vanuatu | VU | 548 |

        | Venezuela, Bolivarian Republic of | VE | 862 |

        | Vietnam | VN | 704 |

        | Wallis and Futuna | WF | 876 |

        | Western Sahara | EH | 732 |

        | Yemen | YE | 886 |

        | Zambia | ZM | 894 |

        | Zimbabwe | ZW | 716 |


        </details>'
      externalDocs:
        description: Find more info here
        url: https://www.iso.org/iso-3166-country-codes.html
      example: NL
    ThreeDsResult:
      type: string
      description: 'The result of the 3DS authentication.

        '
      enum:
      - authenticated
      - non-authenticated
      - attempt
      default: none
    ValidationError:
      type: object
      required:
      - path
      - message
      properties:
        path:
          type: string
          description: A relative path to the error location within the request body.
        errorCode:
          type: string
          description: A code that identifies the error.
        message:
          type: string
          description: A brief description of the validation error.
    common_status:
      type: string
      description: The status of the object
      enum:
      - active
      - archived
    RiskProviderNoCustomerTokenError:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/errorType'
          - enum:
            - /silverflow/problems/riskAssessments/no-customer-token
        title:
          allOf:
          - $ref: '#/components/schemas/errorTitle'
          - enum:
            - No risk provider token found for given agent key
        status:
          allOf:
          - $ref: '#/components/schemas/errorStatus'
          - enum:
            - 409
        detail:
          $ref: '#/components/schemas/errorDetail'
        instance:
          $ref: '#/components/schemas/errorInstance'
    schemas-phoneNumber:
      type: string
      description: An international phone number
      pattern: ^\+\d{2}(\(0\))?\d{3,19}$
      example: +31(0)850609160
    CvcResult:
      enum:
      - none
      - match
      - no-match
      - not-processed
      description: The result of cvc verification.
    openapi_components-schemas-stateOrProvince-2:
      type: string
      minLength: 1
      description: 'The state (US) or province (non-US) of the address.

        '
    AddressInputAlpha2:
      type: object
      required:
      - countryCode
      - city
      - line1
      - postalCode
      additionalProperties: false
      description: 'A physical postal address

        '
      properties:
        countryCode:
          $ref: '#/components/schemas/openapi_components-schemas-countryCodeAlpha2'
        stateOrProvince:
          $ref: '#/components/schemas/openapi_components-schemas-stateOrProvince-2'
        city:
          $ref: '#/components/schemas/openapi_components-schemas-city-2'
        line1:
          $ref: '#/components/schemas/openapi_components-schemas-line1-2'
        line2:
          $ref: '#/components/schemas/openapi_components-schemas-line2-2'
        postalCode:
          $ref: '#/components/schemas/openapi_components-schemas-postalCode-2'
    openapi_components-schemas-line2-2:
      type: string
      minLength: 1
      description: 'Address line 2

        '
    MerchantAcceptorNotFoundError:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/errorType'
          - enum:
            - /silverflow/problems/riskAssessments/merchant-acceptor-not-found
        title:
          allOf:
          - $ref: '#/components/schemas/errorTitle'
          - enum:
            - The merchant acceptor was not found.
        status:
          allOf:
          - $ref: '#/components/schemas/errorStatus'
          - enum:
            - 422
        detail:
          $ref: '#/components/schemas/errorDetail'
        instance:
          $ref: '#/components/schemas/errorInstance'
    openapi_components-schemas-sequence:
      description: 'Required for recurring charges. This field indicates whether a charge is part of a recurring sequence. The initial charge of a recurring sequence should be flagged as `initial`,

        all subsequent transactions should be flagged as `subsequent` and must be sent to the `/charges/{initialChargeKey}/mit` endpoint.


        **From November 22, 2026 this field will be removed since it is not used.**

        '
      type: string
      enum:
      - initial
      - subsequent
      deprecated: true
    openapi_components-schemas-holderName:
      type: string
      description: "The name of the cardholder. In case of AVS, value will be trimmed by the scheme if greater than 26 characters (Visa) or 22 characters (Mastercard).\n\nFor 3DS it will be trimmed if greater than 45 characters  . \n\nMore information here: [Cardholder name restrictions](#section/Cardholder-name-restrictions)\n"
      pattern: ^[\x20-\x7E\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]+$
      minLength: 1
      maxLength: 120
      example: Joe Cardholder
    RiskProviderUnexpectedError:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/errorType'
          - enum:
            - /silverflow/problems/riskAssessments/provider-unexpected
        title:
          allOf:
          - $ref: '#/components/schemas/errorTitle'
          - enum:
            - Request to risk provider returned with unexpected error
        status:
          allOf:
          - $ref: '#/components/schemas/errorStatus'
          - enum:
            - 500
        detail:
          $ref: '#/components/schemas/errorDetail'
        instance:
          $ref: '#/components/schemas/errorInstance'
    errorType:
      type: string
      description: 'A relative URI reference, this property can be used to perform automated error handling.

        '
    FraudioCustomer:
      type: object
      additionalProperties: false
      description: Details of the customer carrying out the transaction
      properties:
        firstName:
          description: The first name of the customer.
          allOf:
          - $ref: '#/components/schemas/components-schemas-NameOfPeopleAndPlaces'
        lastName:
          description: The last name of the customer.
          allOf:
          - $ref: '#/components/schemas/components-schemas-NameOfPeopleAndPlaces'
        email:
          description: The email of the customer.
          allOf:
          - $ref: '#/components/schemas/email'
        phoneNumber:
          description: The phone number of the customer.
          allOf:
          - $ref: '#/components/schemas/schemas-phoneNumber'
    openapi_components-schemas-postalCode-2:
      type: string
      pattern: ^[A-Z0-9]+$
      description: 'The postal code of the address without any spaces.

        '
    schemas-FraudioResult:
      type: object
      additionalProperties: false
      required:
      - score
      - recommendation
      description: A risk assessment result from Fraudio.
      properties:
        score:
          $ref: '#/components/schemas/score'
        recommendation:
          $ref: '#/components/schemas/recommendation'
    openapi_components-schemas-lastModified:
      type: string
      description: The date and time this object was last modified
      format: date-time
      readOnly: true
    schemas-OutputCard:
      type: object
      required:
      - last4
      additionalProperties: false
      description: 'Card data

        '
      properties:
        last4:
          type: string
          pattern: ^[0-9]+$
          minLength: 4
          maxLength: 4
          example: 0905
    openapi_components-schemas-created-2:
      type: string
      description: The date and time this object was created
      format: date-time
      readOnly: true
    openapi_components-schemas-line1-2:
      type: string
      minLength: 1
      description: 'Address line 1

        '
    components-schemas-CardInput:
      type: object
      required:
      - number
      - expiryMonth
      - expiryYear
      additionalProperties: false
      description: 'Card data

        '
      properties:
        number:
          $ref: '#/components/schemas/openapi_components-schemas-pan-3'
        expiryMonth:
          $ref: '#/components/schemas/expiryMonth'
        expiryYear:
          $ref: '#/components/schemas/expiryYear'
        holderName:
          $ref: '#/components/schemas/openapi_components-schemas-holderName'
    openapi_components-schemas-ChargeType-2:
      description: 'Describes the kind of charge the merchant wants to submit.

        '
      type: object
      required:
      - intent
      - cardEntry
      - order
      properties:
        intent:
          $ref: '#/components/schemas/intent'
        cardEntry:
          $ref: '#/components/schemas/openapi_components-schemas-cardEntry-2'
        order:
          $ref: '#/components/schemas/components-schemas-order'
        sequence:
          $ref: '#/components/schemas/openapi_components-schemas-sequence'
        terminalEntryMode:
          $ref: '#/components/schemas/openapi_components-schemas-terminalEntryMode'
  examples:
    perform-risk-assessment-fraudio:
      value:
        provider: fraudio
        merchantAcceptorKey: mac-1JRadf2ffdfrdPMf2XrS2
        card:
          number: '1234123412341234'
          expiryMonth: 1
          expiryYear: 2020
          holderName: Joe Cardholder
        amount:
          value: 900000000
          currency: EUR
        chargeType:
          intent: purchase
          cardEntry: e-commerce
          order: checkout
          sequence: initial
          terminalEntryMode: contactless
    perform-risk-assessment-cybersource:
      value:
        provider: cybersource
        merchantAcceptorKey: mac-1JRadf2ffdfrdPMf2XrS2
        card:
          number: '1234123412341234'
          expiryMonth: 1
          expiryYear: 2020
          holderName: Joe Cardholder
        amount:
          value: 900000000
          currency: EUR
        chargeType:
          intent: purchase
          cardEntry: e-commerce
          order: checkout
          sequence: initial
          terminalEntryMode: contactless
        customer:
          firstName: Joe
          lastName: Cardholder
          email: joecardholder@example.com
          phoneNumber: +31(0)12345678
          billingAddress:
            countryCode: US
            stateOrProvince: Pennsylvania
            city: Scranton
            line1: 1725 Slough Avenue
            line2: Suite 200
            postalCode: '18503'
        localTransactionDateTime: '2019-08-24T14:15:22Z'
        authentication:
          cvc: none
          avs: none
          threeDsResult: authenticated
        authorizationFields:
          responseCode: '00'
          eci: '5'
    components-examples-InvalidInputErrorExample:
      value:
        type: /silverflow/problems/invalid-input
        title: Invalid Input
        status: 400
        detail: The request does not adhere to the defined API schema.
        instance: /silverflow/b4cc37a0-ab24-46b4-aa8c-cc2d6eddf1b6
        validationErrors:
        - path: /body/card/number
          message: must have required property 'number'
          errorCode: required.openapi.validation
  securitySchemes:
    ApiKey:
      description: "The primary method of authenticating to the Silverflow API is through API keys.\n\nAPI keys can be created by calling the [createApiKey](#operation/createApiKey) endpoint. You can create up to 40 API keys and also update and delete them, allowing for _credential rotation_.\n\nThe _Agent Activation_ process will generate an initial API Key for you. See [Activate Agent](#section/Getting-Started).\n\nA call to the [createApiKey](#operation/createApiKey) endpoint will return the following structure:\n\n```json\n{\n    \"key\": \"apk-1wtRxni5IsPsSpBLWpwr\",\n    \"status\": \"active\",\n    \"agentKey\": \"cgt-1wtRvFLIjDOyyUR5Q2LB\",\n    \"description\": \"Data lake API key\",\n    \"permissions\": [\n        \"charges:List\",\n        \"reports:All\"\n    ],\n    \"created\": \"2021-06-22T11:21:45.115Z\",\n    \"secret\": \"FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ\",\n    \"version\": 1\n}\n```\n\n> **Important:** The `secret` is only returned once in the response to the `createApiKey` call.\n\nOnce created, the `key` and `secret` fields from the API key must be used in the HTTP `Authorization` header using the `Basic` scheme.\nThe Basic scheme requires a **username** and **password** to be specified, separated by a `:` (colon) and Base64 encoded.\n\nUse the following values from the API key to construct a Basic authentication header:\n\n| Basic field | API key field | Example |\n| ----------- | ------------- | ------- |\n| username | `key` | `apk-1wtRxni5IsPsSpBLWpwr` |\n| password | `secret` | `FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ` |\n\nIn pseudo-code a valid HTTP Basic Authentication header would be constructed as follows:\n\n```ts\nconst apiKeyId = \"apk-1wtRxni5IsPsSpBLWpwr\";\nconst apiKeySecret = \"FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ\";\nconst authnValue = \"Basic \" + base64Encode(apiKeyId + \":\" + apiKeySecret);\nrequest.setHeader(\"Authorization\", authnValue);\n```\n\nUsing the values from the example a valid HTTP request would look like the following:\n\n```http\nGET /v1/agents/current HTTP/1.1\nAccept: application/json\nAuthorization: Basic YXBrLTF3dFJ4bmk1SXNQc1NwQkxXcHdyOkZXdG5PT0hBamJENnJOeFdXRWVWT0NqN0pYU0VQR0pR\n```\n\nMore information on the Basic scheme can be found in [RFC-7617 - The 'Basic' HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617)."
      type: http
      scheme: basic
    BearerToken:
      description: 'Bearer tokens are temporary security credentials that can be used to authorize ''third parties'' (bearers) access to the Silverflow API on behalf of the agent.


        These tokens are created by calling the [createAgentBearerToken](#operation/createAgentBearerToken) endpoint.


        Once created the `token` field must be used in the HTTP `Authorization` header using the `Bearer` scheme.

        Here''s an example of an HTTP request with a bearer token:


        ```http

        GET /v1/merchants/mct-1hPdFhmgaBzMS191nIbJ HTTP/1.1

        Accept: application/json

        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...40EFOgxf_3I6mPZ16bXqHd5tUyApgl0mNOAXPm5AhnA


        ```


        More information on the Bearer scheme can be found in [RFC-6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750).'
      type: http
      scheme: bearer
      bearerFormat: JWT
    MutualTLS:
      type: apiKey
      in: header
      name: '-'
      description: 'The client must set up mTLS connection with a valid X.509 client certificate signed by a customer-provided CA (certificate authority) that is registered to a specific agent. The customer-provided CA certificate must be shared and added to Silverflow''s trust store prior to calling endpoints.


        Certificate validation happens at the transport layer during TLS handshake. Tenant verification is performed by matching the agent key embedded in the client certificate against the agent key embedded in the trusted CA.

        '
x-refined-from:
- silverflow-openapi.yml
- silverflow-openapi.yml
x-tagGroups:
- name: ''
  tags:
  - Introduction
  - Release Notes
- name: Accounts
  tags:
  - Agents
  - API Keys
  - Bins
  - Merchants
  - Merchant Acceptors
  - Enrollments
  - Screenings
- name: Event Notifications
  tags:
  - Event Subscriptions
  - Charges Events
  - Disputes Events
  - Fraud Notification Events
  - Processor Tokens Events
  - Network Tokens Events
  - Report Events
  - Distribution Events
  - AMMF Submission Events
  - Reconciliation Events
  - Clearing Events
- name: 3DS Authentication
  tags:
  - 3DS Authentication
- name: BEP Authentication
  tags:
  - BEP Authentication
- name: Tokenization
  tags:
  - Processor Tokenization
  - Network Tokenization
- name: Charges
  tags:
  - Create Charges
  - Create Recurring
  - Retrieve Charges
  - Charge Actions
- name: Terminal-To-Cloud
  tags:
  - Create POS Charges
  - Retrieve POS Charges
  - POS Charge Actions
- name: Card Management
  tags:
  - Card Management
- name: Disputes
  tags:
  - Disputes
  - Documents
- name: Fraud Notifications
  tags:
  - Fraud Notifications
- name: Card Info
  tags:
  - Card Info
- name: Currency Conversion Rates
  tags:
  - Currency Conversion Rates
- name: Fees
  tags:
  - Fees
- name: Reconciliation
  tags:
  - Reconciliation Details
  - Network Funds Transfers
- name: Reports
  tags:
  - Reconciliation Reports
  - Settlement Reports
  - Card Network Reports
  - Dispute Reports
  - Fraud Notifications Reports
  - Charges Reports
  - Scheme Fee Reports
  - Retrieve Reports
  - Report Scheduling
  - Distributions
- name: Transaction Risk Assessment
  tags:
  - Transaction Risk Assessment
- name: File Subscriptions
  tags:
  - File Subscriptions