openapi: 3.0.0
info:
  description: >
    Use this API to access and manage your **WePayments** account data


    All endpoints are available via `https` and are located at
    api.wepayout.com/v1/payout/.


    Last update: 2021-12-14
  version: 1.2.1
  title: WePayments API
  termsOfService: https://www.wepayout.com/terms/
  contact:
    email: it-support@wepayout.co
  license:
    name: WePayments
    url: https://wepayout.co
tags:
  - name: Data Qualification
    description: >
      Manage your data qualification data The data qualification process has the
      objectve to validate and qualify bank account data.
paths:
  /v1/payout/data-qualification/services:
    get:
      security:
        - Authorization: []
      tags:
        - Data Qualification
      summary: |
        Data qualification services available
      description: >
        The data qualification services determine the procedures that will be
        applied to qualify the bank account.

        We have five data qualification services available:
          * 1: - Automatic validation: validates the document and bank account digits.
          * 2: - Automatic validation + micro deposit: After the data is validated a micro deposit is made to the account to assure that it's valid.
          * 3: - Automatic validation + micro deposit + manual correction: Same as above plus manual check in case of failures.
          * 4: - Automatic validation + deposit. Same as 2 but you provide the amount to be deposited.
          * 5: - Automatic validation + deposit + manual correction: Same as 3 but you provide the amount to be deposited.
      responses:
        '200':
          description: |
            The services list
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DataQualificationService'
    parameters: []
  /v1/payout/data-qualification:
    post:
      security:
        - Authorization: []
      tags:
        - Data Qualification
      callbacks:
        dataQualificationStatus:
          https://your.endpoint.to.update:
            post:
              summary: Receive data qualification status updates.
              description: >
                All data qualification webhooks are signed with an sha256 hash
                provided in the `Authorization` header.\

                The hash is sent as a Bearer token. eg.: `Bearer {hash}`

                To validate the signature you must concatenate the request body
                and your APIKey used to create the payments and hash this string
                using the sha256 algorithm.\

                For example: {JSON_BODY...}APIKEY
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      $ref: '#/components/schemas/Notification'
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
      summary: |
        Register a batch of data qualification orders
      description: >
        You can use this endpoint to create a data qualification batch.

        In the data attribute you may pass a list of bank account datas to be
        qualified. 

        You can group your data qualification in batches, to do so use the field
        `batch_code`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataQualificationRequest'
        description: Data Qualification creation
        required: true
      responses:
        '200':
          description: >
            All data qualification records provided have been successfully
            processed.
        '400':
          description: >
            When some of the records provided in the data list have errors
            during processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataQualificationUploadError'
    get:
      security:
        - Authorization: []
      tags:
        - Data Qualification
      summary: List all data qualifications
      description: >
        A paginated, filterable and sortable list of DataQualification 
        processes.
      parameters:
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/page'
        - name: order_by
          in: query
          description: |
            The field that will be used to sort data.
          required: false
          schema:
            type: string
            enum:
              - id
              - data_qualification_service_name
              - batch_code
              - custom_code
              - merchant.name
              - description_status
              - created_at
            default: id
        - name: sort
          in: query
          description: |
            The sort type, asc or desc
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: created_at
          in: query
          description: |
            Created at filter:
             - created_at=2020-01-01
          required: false
          schema:
            type: string
        - name: custom_code
          in: query
          description: |
            Filter by custom_code (invoice):
             - custom_code:abc001
          required: false
          schema:
            type: string
        - name: document
          in: query
          description: |
            Filter by the beneficiary's document:
             - document:00000000000 
          required: false
          schema:
            type: string
        - name: data_qualification_service_id
          in: query
          description: >
            Filter by qualification service 

            You can list the available options in the endpoint [GET
            /data-qualification/services](#tag/Data-Qualification/paths/~1data-qualification~1services/get)
          required: false
          schema:
            type: integer
        - name: merchant_id
          in: query
          description: |
            Filter by merchant_id
          required: false
          schema:
            type: integer
        - name: status_flow_data_qualification_id
          in: query
          description: >
            Filter by status

            You can list the available options in the endpoint [GET
            /data-qualification/status](#tag/Data-Qualification/paths/~1data-qualification~1status/get)
          schema:
            type: string
      responses:
        '200':
          description: |
            A data qualification data list
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DataQualification'
    parameters: []
  /v1/payout/data-qualification/{id}:
    get:
      security:
        - Authorization: []
      tags:
        - Data Qualification
      summary: |
        Get a data qualification order by ID
      description: |
        Return the informations for an specific data qualification process
      parameters:
        - in: path
          name: id
          required: true
          description: |
            The data qualification id
          schema:
            type: integer
      responses:
        '200':
          description: |
            The data qualification object
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DataQualification'
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
  /v1/payout/data-qualification/status:
    get:
      security:
        - Authorization: []
      tags:
        - Data Qualification
      summary: |
        Get the statuses available
      description: |
        A list with all status available
        Status Descriptions:
          * `1` - Received: Payment received and stored in our database
          * `5` - Valid data: The account data is valid
          * `6` - Invalid data: Payment rejected by the bank
          * `7` - Validation not possible on this step: The account data provided can not be validated
          * `9` - Awaiting - Awaiting balance to be processed
          * `999` - Processing: Payment sent for processing
      parameters:
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: |
            The statuses list
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatusFlowDataQualification'
    parameters: []
  /v1/payout/data-qualification/custom-code/{customCode}:
    parameters:
      - schema:
          type: string
        name: customCode
        in: path
        required: true
    get:
      summary: Find a data qualification order using custom code
      tags:
        - Data Qualification
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataQualification'
      operationId: get-data-qualification-custom-code-id
servers:
  - url: https://api.wepayout.com.br
  - url: https://api.sandbox.wepayout.com.br
components:
  parameters:
    authorization:
      in: header
      name: Authorization
      description: The authorization token
      required: true
      schema:
        type: string
    per_page:
      in: query
      name: per_page
      required: false
      description: The number of items that will be displayed per page on paginated lists.
      schema:
        type: integer
        minimum: 0
    page:
      in: query
      name: page
      required: false
      description: The current page that will be displayed on paginated lists.
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: WePayments offers an RFC 6750 Bearer Token authentication method
  schemas:
    Beneficiary:
      type: object
      required:
        - name
        - document
        - bank_branch
        - account
        - account_digit
        - account_type
        - bank_code
        - document_type
      properties:
        name:
          type: string
          example: The Name
        bank_code:
          type: string
          example: '147'
        bank_branch:
          type: string
          example: '0000'
        bank_branch_digit:
          type: string
          example: '1'
        account:
          type: string
          example: '1030000'
        account_digit:
          type: string
          example: '1'
        account_type:
          type: string
          enum:
            - SAVINGS
            - CHECKING
          example: CHECKING
          description: SAVINGS or CHECKING
        document:
          type: string
          example: '12533009091'
          description: CPF or CNPJ Number
        document_type:
          type: string
          enum:
            - cpf
            - cnpj
          example: cpf
          description: CPF or CNPJ
        birthdate:
          type: string
          example: '1970-01-01'
        phone:
          type: string
          example: '5541987456321'
        city:
          type: string
          example: Curitiba
        postal_code:
          type: string
          example: 80200-100
        province_code:
          type: string
          example: PR
        address:
          type: string
          example: Rua a Número 10
    BeneficiaryRequest:
      type: object
      required:
        - name
        - document
        - bank_branch
        - account
        - account_digit
        - account_type
        - bank_code
        - document_type
      properties:
        name:
          type: string
          example: The Name
        bank_code:
          type: string
          example: '147'
        bank_branch:
          type: string
          example: '0000'
        bank_branch_digit:
          type: string
          example: '1'
        account:
          type: string
          example: '1030000'
        account_digit:
          type: string
          example: '1'
        account_type:
          type: string
          enum:
            - SAVINGS
            - CHECKING
          example: CHECKING
          description: SAVINGS or CHECKING
        document:
          type: string
          example: '12533009091'
          description: CPF or CNPJ Number
    StatusFlowDataQualification:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: Status ID
          example: 1
        name:
          type: string
          description: Name status
          example: received
    DataQualificationRequest:
      type: object
      properties:
        merchant_id:
          type: integer
          description: >-
            The Merchant ID, Required when you have access to more than one
            Merchant
        service_id:
          type: integer
          description: >
            The service ID The avaliable service can be retrived in the endpoint
            [GET
            /data-qualification/services](#tag/Data-Qualification/paths/~1data-qualification~1services/get)
          minimum: 1
          maximum: 5
        data:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
                description: Amount in local currency, used in services 4 and 5 only.
                example: 1000
                format: float
                minimum: 0.01
                maximum: 150000
              custom_code:
                type: string
                description: Custom code (Invoice) must be unique in our database
                example: YourCustomCode
              batch_code:
                type: string
                description: The code used to group data qualification process
                example: YOURAPPCODE
              notification_url:
                type: string
                description: >-
                  We will send you a HTTP POST with a Notification Object when
                  deposit status changes
                example: https://your.endpoint.to.update
              beneficiary:
                $ref: '#/components/schemas/BeneficiaryRequest'
            required:
              - custom_code
              - batch_code
              - beneficiary
      required:
        - service_id
        - data
    Notification:
      description: >-
        This object is sent as a HTTP POST when you provide a notificationUrl in
        DataQualification creation
      type: object
      properties:
        id:
          type: string
          description: Our Id
          example: '1'
        step:
          type: integer
          description: >
            An integer value that indicates the step that the data-qualification
            process is.

            Can be the following:

            * `1` - Processing - Intermediary step

            * `2` - Valid data - Final step

            * `3` - Invalid data - Final step
        status_id:
          type: integer
          description: >
            An integer value that indicates the current data-qualification
            status.

            Can be the following:

            * `1` - Received - The data qualification is received and will be
            processed soon

            * `5` - Valid data - Final status

            * `6` - Invalid data - Final status

            * `7` - No Process - The account can not be validated - Final status
        custom_code:
          type: string
          description: Your Custom Code
          example: YOURAPPCODE
        batch_code:
          type: string
          description: The data qualification batch code
          example: bc101
        message:
          type: string
          description: |
            The description of the data qualification update  
            Can be one of the following messages:
            - Received
            - Correcting Data
            - Sent to payout
            - Sent for manual processing
            - Original data sent is correct
            - Data is invalid
            - Canceled
            - Updated Data
            - Document ID invalid
            - Processing Manually
            - Processing Payment
            - Payment Rejected
            - Errors not found
            - Bank account digit corrected
            - Invalid data with account digit correction
            - Invalid data
            - Bank account error
            - Wrong bank details
            - We cannot process
            - Account number is invalid
            - Incorrect bank details
            - Processing Manually
            - Data could not be qualified
            - There is no balance to create the payment
            - Waiting
            - Invalidated by manual
            - Correction applied on data sent
          example: ''
        name:
          type: string
        document:
          type: string
        bank_code:
          type: string
        bank_branch:
          type: string
        bank_branch_digit:
          type: string
        account:
          type: string
        account_digit:
          type: string
        account_type:
          type: string
          description: '`c`for Checking accounts,`s`for Savings accounts'
        pix_key:
          type: string
    DataQualification:
      type: object
      properties:
        id:
          type: integer
          description: Our id
          example: 123
        batch_code:
          type: string
          description: Batch code
          example: abc101
        custom_code:
          type: string
          description: Your id in our database, must be unique
          example: cc102
        data_qualification_service_name:
          type: string
          description: Service name
          example: Data validation
        status_flow_data_qualification_id:
          type: integer
          description: Data qualification status id
          example: 1
        data_qualification_status_flow_name:
          type: string
          description: Data qualification status name
          example: Processing
        description_status:
          type: string
          description: Data qualification status description
          example: Processando
        name:
          type: string
          description: Beneficiary name
          example: Maria Jose
        document:
          type: string
          example: '12345678909'
          description: Beneficiary document
        bank_code:
          type: string
          example: '104'
          description: Bank code
        bank_branch:
          type: string
          example: '0123'
          description: Bank branch
        bank_branch_digit:
          type: string
          example: '0'
          description: Bank branch digit
        account:
          type: string
          example: '123456'
          description: Bank account
        account_digit:
          type: string
          example: '1'
          description: Bank account digit
        account_type_name:
          type: string
          example: Checking account
          description: Account type
        amount:
          type: number
          example: 1.1
          description: Source amount
        created_at:
          type: string
        updated_at:
          type: string
        merchant:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
    DataQualificationUploadError:
      type: object
      properties:
        message:
          type: string
          example: Error message.
        info:
          type: object
          description: |
            This return object is divided in tree properties:
             - errors: Contains the records that have any error during processement.
             - uploadSucces: Contains the records that have been successfuly processed.
             - uploadChangeService: The records that have the service changed automatically.
          properties:
            errors:
              items:
                type: object
                properties:
                  line:
                    type: integer
                    example: 1
                    description: |
                      Represents which record in the batch data have errors
                  batch_code:
                    type: string
                    example: bc101
                    description: |
                      The batch_code provided
                  custom_code:
                    type: string
                    example: cc101
                    description: |
                      The custom_code provided
                  message:
                    type: string
                    example: Name format invalid
                    description: |
                      Message error description
            uploadSuccess:
              items:
                type: object
                properties:
                  line:
                    type: integer
                    example: 1
                    description: |
                      Represents which record in the batch data have errors
                  batch_code:
                    type: string
                    example: bc102
                    description: |
                      The batch_code provided
                  custom_code:
                    type: string
                    example: cc102
                    description: |
                      The custom_code provided
            uploadChangeService:
              items:
                type: object
                properties:
                  line:
                    type: integer
                    example: 1
                    description: |
                      Represents which record in the batch data have errors
                  batch_code:
                    type: string
                    example: bc101
                    description: |
                      The batch_code provided
                  custom_code:
                    type: string
                    example: cc101
                    description: |
                      The custom_code provided
                  message:
                    type: string
                    example: Data qualification by system
                    description: |
                      The new service assigned to record. 
    DataQualificationService:
      type: object
      items:
        properties:
          id:
            type: integer
            example: 1
          name:
            type: string
            example: Data qualification manually
