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: 2023-11-13
  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 Collect
    description: >
      The data collection lasts for 30 days. This process involves making a
      payment to the beneficiary with the provided bank details. If
      unsuccessful, we will attempt to contact the beneficiary to inform them
      about the data collection. Upon receiving a response, we will try to
      process the payment again to validate the bank details. The data
      collection will be automatically canceled on the 30th day if we do not
      receive any response from the beneficiary.
paths:
  /v1/payout/refunds:
    post:
      tags:
        - Data Collect
      summary: Data Collect Creation
      description: >
        The data collection statuses are:


        First status:
          - RECEIVED: First status when the data collection is created;
            - Status ID: 1

        Intermediary statuses:
          - COLLECTING_DATA: We are collecting the beneficiary's data; no payment attempts have been made yet.
            - Status ID: 14
          - PROCESSING_PIX_DATA_COLLECTED: Beneficiary's data received; payment attempt made.
            - Status ID: 8
          - PROCESSING_PIX_CPF: Payment processing using CPF as PIX Key.
            - Status ID: 2
          - PROCESSING_PIX_BANK_DATA: Payment processing using Pix with the provided banking information.
            - Status ID: 13
        - PROCESSING_PIX_KEY: Payment processing using Pix with the key of any
        type that was sent in the field `pix_key`.
          - Status ID: 15
          
        Finished statuses:
          - CANCELED: Enters this final status after 30 days without successful data collection.
            - Status ID: 11
          - PAID: Data collection successful; payment received."
            - Status ID: 12
      operationId: post-payout-refunds
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataCollectCreateResponse'
              examples:
                Example 1:
                  value:
                    id: 12345
                    direct_payment: 1
                    hash: 1803e619-467b-48a0-a6b6-28f0757e3c0d
                    merchant:
                      id: 358
                      name: Merchant's name
                    status:
                      id: 1
                      name: Received
                    last_event:
                      id: null
                      name: ''
                    name: Beneficiary's name
                    document: '01234567890'
                    email: email@gmail.com
                    phone: '123456789'
                    bank_code: '001'
                    bank_branch: '1234'
                    account: '2333'
                    account_digit: '1'
                    account_type: CHECKING
                    notification_url: https://test.requestcatcher.com/test
                    amount: 15000
                    invoice: 42f7df50-b80d-4ae8-b741-bc5bc4a83a65
                    description: null
                    created_at: '2023-11-24T14:37:39.565469Z'
                    updated_at: '2023-11-24T14:37:39.565469Z'
                    bank:
                      code: '001'
                      name: 001 - BCO DO BRASIL S.A.
                    status_history: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  name_of_the_field_with_error:
                    type: array
                    x-stoplight:
                      id: rqh2m18aj7vz0
                    description: >-
                      When one or more fields have errors, the application will
                      return all the fields with errors.
                    items:
                      x-stoplight:
                        id: sgn3mi7f9qdq4
                      type: string
              examples:
                Example 1:
                  value:
                    invoice:
                      - Duplicate invoice
                    document:
                      - The document must be between 11 and  15 digits.
                      - Is not a valid cpf/cnpj 111
                    email:
                      - The email must be a valid email address.
                      - Is not a valid email emailgmail.com
                    pix_key:
                      - >-
                        Pix key type not identified. Review the pix_key value.
                        123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataCollectCreateBody'
            examples:
              Example 1:
                value:
                  merchant_id: 123
                  invoice: invoice2323
                  amount: 15000
                  name: Beneficiary's name
                  document: '01234567890'
                  email: email@gmail.com
                  phone: '123456789'
                  pix_key: '35489217650823194760983471254982'
                  bank_code: '001'
                  bank_branch: '1234'
                  account: '2333'
                  account_digit: '1'
                  account_type: CHECKING
                  direct_payment: 1
                  notification_url: https://test.requestcatcher.com/test
      callbacks:
        dataCollectStatus:
          https://your.endpoint.to.update:
            post:
              summary: Receive status updates on data collection.
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/WebhookDataCollect'
                    examples:
                      Example 1:
                        value:
                          id: 123
                          invoice: e0dcf1d7-c0f6-43de-a426-ed8d1f5e4863
                          status:
                            id: 13
                            name: Processing PIX - BANK ACCOUNT
                            created_at: '2023-11-24T17:21:34.286753Z'
    parameters: []
  /v1/payout/refunds/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      tags:
        - Data Collect
      summary: Data Collection Retrieval by ID
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataCollectGetResponse'
              examples:
                Example 1:
                  value:
                    id: 12345
                    direct_payment: 1
                    hash: 1803e619-467b-48a0-a6b6-28f0757e3c0d
                    merchant:
                      id: 358
                      name: Merchant name
                    status:
                      id: 12
                      name: Paid
                    last_event:
                      id: 9
                      name: Payment processing
                    name: Beneficiary's name
                    document: '01234567890'
                    email: email@gmail.com
                    phone: '123456789'
                    pix_key: '35489217650823194760983471254982'
                    bank_code: '001'
                    bank_branch: '1234'
                    account: '2333'
                    account_digit: '1'
                    account_type: CHECKING
                    notification_url: https://test.requestcatcher.com/test
                    amount: 15000
                    invoice: 42f7df50-b80d-4ae8-b741-bc5bc4a83a65
                    description: null
                    created_at: '2023-11-24T14:37:39.565469Z'
                    updated_at: '2023-11-24T14:39:34.624073Z'
                    bank:
                      code: '001'
                      name: 001 - BCO DO BRASIL S.A.
                    status_history:
                      - type: status
                        id: 13
                        name: Processing PIX - BANK ACCOUNT
                        created_at: '2023-11-24T14:38:33.763587Z'
                      - type: event
                        id: 9
                        name: Payment processing
                        created_at: '2023-11-24T14:38:34.352586Z'
                      - type: status
                        id: 12
                        name: Paid
                        created_at: '2023-11-24T14:39:34.664901Z'
                    payments:
                      - status:
                          id: 13
                          name: Processing PIX - BANK ACCOUNT
                        payment:
                          id: 1234567
                          amount: 15000
                          authentication_code: null
                          rejection_description: ''
                          status:
                            id: 2
                            name: Processing
                          paid_at: null
                          created_at: '2023-11-24T14:38:34.000000Z'
                          description: null
                          custom_code: Refund-12987-024112023113833
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Reason for the error.
                  error:
                    type: string
                    description: Error code.
              examples:
                Example 1:
                  value:
                    message: Refund not found
                    error: '404'
      operationId: get-payout-refunds-id
      description: >-
        This endpoint returns your data collection based on the ID provided in
        the route.
      parameters: []
components:
  schemas:
    DataCollectCreateBody:
      title: DataCollectCreateBody
      x-stoplight:
        id: 4eb2b18a3900e
      type: object
      properties:
        merchant_id:
          type: integer
          description: It must be your merchant_id given in the integration.
        invoice:
          type: string
          maxLength: 45
        amount:
          type: number
          minimum: 0.01
          maximum: 150000
        name:
          type: string
          maxLength: 150
        document:
          type: string
          example: '01234567890'
          description: Exactly 11 or 14 numbers.
        email:
          type: string
        phone:
          type: string
          example: '+5541999998888'
        pix_key:
          type: string
          x-stoplight:
            id: euerm60r6j7sa
          description: >-
            When you have a PIX key, but you don't know the type, you can send
            it to us, and we will try to make a payment for this key if the
            field `direct_payment` is equal to 1.
        direct_payment:
          type: integer
          description: >-
            If 1, a PIX payment will be created before sending a notification
            email to collect the beneficiary bank data; if 0, the email will be
            sent before making the PIX payment.
          enum:
            - 0 or 1
        notification_url:
          type: string
          maxLength: 140
          description: |-
            A POST endpoint where the refund status updates
            will be sent. (under development).
        description:
          type: string
          description: The description shown on the payment.
          maxLength: 140
        bank_code:
          type: string
          example: '001'
          description: >-
            Exactly 3 digits.

            mandatory if `bank_branch`, `account`, `account_digit`and
            `account_type`are provided.
        bank_branch:
          type: string
          maxLength: 5
        account:
          type: string
          maxLength: 16
        account_digit:
          type: string
          description: Max 1 digit.
        account_type:
          type: string
          enum:
            - S
            - s
            - C
            - c
            - CHECKING
            - SAVINGS
      required:
        - merchant_id
        - invoice
        - amount
        - name
        - document
        - email
        - phone
        - direct_payment
    DataCollectCreateResponse:
      type: object
      x-examples:
        Example 1:
          id: 11430
          direct_payment: null
          hash: b53e30f4-ed45-422f-b3dc-3f85f91f2c95
          merchant:
            id: 1
            name: YourCompany
          status:
            id: 1
            name: Recebido
          last_event:
            id: null
            name: ''
          name: Example Beneficiary Name
          document: '01234567890'
          email: cliente@gmail.com
          phone: '+5541999991111'
          bank_code: null
          bank_branch: null
          account: null
          account_digit: null
          account_type: null
          notification_url: null
          amount: 0.01
          invoice: e0aae139-680a-4928-b3e2-6785621fb385
          description: aaa
          created_at: '2023-03-07T18:42:22.212676Z'
          updated_at: '2023-03-07T18:42:22.212676Z'
          status_history: []
      title: DataCollectCreateResponse
      x-stoplight:
        id: 2a44a795f214a
      properties:
        id:
          type: integer
        direct_payment:
          type: integer
        hash:
          type: string
        merchant:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        status:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        last_event:
          type: object
          properties:
            id:
              nullable: true
            name:
              type: string
              description: Upon creation, this field is always an empty string.
        name:
          type: string
        document:
          type: string
        email:
          type: string
        phone:
          type: string
        bank_code:
          type: string
        bank_branch:
          type: string
        account:
          type: string
        account_digit:
          type: string
        account_type:
          type: string
        notification_url:
          type: string
        amount:
          type: number
        invoice:
          type: string
        description:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        status_history:
          type: array
          description: This field is always an empty list upon creation.
          items:
            type: object
            properties:
              type:
                type: string
              id:
                type: integer
              name:
                type: string
              created_at:
                type: string
    WebhookDataCollect:
      type: object
      properties:
        id:
          type: integer
        invoice:
          type: string
        status:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
            created_at:
              type: string
      x-examples:
        Example 1:
          id: 2
          invoice: e439f78b-57a3-4c2d-b43d-c5d3e31d2442
          status:
            id: 35605
            name: Processing PIX - CPF
            created_at: '2023-03-08T21:36:11.409578Z'
      title: Webhook data collect
      description: ''
      x-stoplight:
        id: 310ef26148120
    DataCollectGetResponse:
      type: object
      x-examples:
        Example 2:
          id: 12345
          direct_payment: 1
          hash: 1803e619-467b-48a0-a6b6-28f0757e3c0d
          merchant:
            id: 358
            name: Merchant name
          status:
            id: 12
            name: Paid
          last_event:
            id: 9
            name: Payment processing
          name: Benefiary's name
          document: '01234567890'
          email: email@gmail.com
          phone: '123456789'
          bank_code: '001'
          bank_branch: '1234'
          account: '2333'
          account_digit: '1'
          account_type: CHECKING
          notification_url: https://teste1713913769.requestcatcher.com/test
          amount: 15000
          invoice: 42f7df50-b80d-4ae8-b741-bc5bc4a83a65
          description: null
          created_at: '2023-11-24T14:37:39.565469Z'
          updated_at: '2023-11-24T14:39:34.624073Z'
          bank:
            code: '001'
            name: 001 - BCO DO BRASIL S.A.
          status_history:
            - type: status
              id: 13
              name: Processing PIX - BANK ACCOUNT
              created_at: '2023-11-24T14:38:33.763587Z'
            - type: event
              id: 9
              name: Payment processing
              created_at: '2023-11-24T14:38:34.352586Z'
            - type: status
              id: 12
              name: Paid
              created_at: '2023-11-24T14:39:34.664901Z'
          payments:
            - status:
                id: 13
                name: Processing PIX - BANK ACCOUNT
              payment:
                id: 2320538
                amount: 15000
                authentication_code: null
                rejection_description: ''
                status:
                  id: 2
                  name: Processing
                paid_at: null
                created_at: '2023-11-24T14:38:34.000000Z'
                description: null
                custom_code: Refund-12987-024112023113833
      properties:
        id:
          type: integer
        direct_payment:
          type: integer
        hash:
          type: string
        merchant:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        status:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        last_event:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        name:
          type: string
        document:
          type: string
        email:
          type: string
        phone:
          type: string
        pix_key:
          type: string
          x-stoplight:
            id: 6g20v4bmgq2zq
        bank_code:
          type: string
        bank_branch:
          type: string
        account:
          type: string
        account_digit:
          type: string
        account_type:
          type: string
        notification_url:
          type: string
        amount:
          type: integer
        invoice:
          type: string
        description:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        bank:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
        status_history:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: Can be an `event` or a `status`.
              id:
                type: integer
              name:
                type: string
              created_at:
                type: string
        payments:
          type: array
          description: >-
            It is only provided when a payment attempt is made; otherwise, this
            field will not exist.
          items:
            type: object
            properties:
              status:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
              payment:
                type: object
                properties:
                  id:
                    type: integer
                  amount:
                    type: integer
                  authentication_code:
                    type: string
                    nullable: true
                  rejection_description:
                    type: string
                  status:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                  paid_at:
                    type: string
                    format: date-time
                    nullable: true
                  created_at:
                    type: string
                  description:
                    type: string
                    nullable: true
                  custom_code:
                    type: string
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: WePayments offers an RFC 6750 Bearer Token authentication method
servers:
  - url: https://api.wepayout.com.br
  - url: https://api.sandbox.wepayout.com.br
