openapi: 3.0.0
info:
  title: Remittances API
  version: 2.0.0
  description: API to receive remittances.
paths:
  /v2/remittances/receive:
    post:
      summary: Create a private account and receive remittance
      operationId: createPrivateAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiveRemittanceRequest'
      responses:
        '200':
          description: Remittance received successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiveRemittanceResponse'
  /v2/remittances/receive_reversal:
    delete:
      summary: Reverse a remittance transaction
      description: Allows reversing a remittance only on the same day of the operation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiveReversalRequest'
            example:
              amount: '1596.00'
              reference: '23033104'
              reversal_reason: WRONG_TX
      responses:
        '200':
          description: Successful reversal of the remittance transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiveReversalResponse'
              example:
                status: reversed
                reversal_date_time: '2025-03-28T00:36:54.000Z'
        '400':
          description: Invalid request or remittance cannot be reversed.
        '403':
          description: Reversal period expired.
  /v2/remittances/references:
    get:
      summary: Search for a remittance by reference number
      description: Retrieves remittance details based on the provided reference number.
      parameters:
        - name: reference_number
          in: query
          required: true
          description: The reference number of the remittance.
          schema:
            type: string
            example: '23033104'
      responses:
        '200':
          description: Successful response with remittance details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceResponse'
  /v2/remittances/transaction:
    post:
      summary: Create a remittance transaction
      operationId: createRemittanceTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransactionRequest'
            example:
              mgi_transaction_session_id: 4200922151E1743120525540
              product_type: RCV
      responses:
        '200':
          description: Transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTransactionResponse'
              example:
                transaction_id: 132
                status: received
                reference: '23033104'
                transaction_date_time: '2025-03-28T00:31:58.206Z'
components:
  schemas:
    ReceiveRemittanceRequest:
      type: object
      properties:
        mgi_transaction_session_id:
          type: string
          example: 4200922151E1743120525540
        reference:
          type: string
          example: '23033104'
        amount:
          type: string
          example: '1596.00'
        currency:
          type: string
          example: MXN
        country:
          type: string
          example: MEX
        state:
          type: string
          example: DF
        city:
          type: string
          example: Miguel Hidalgo
        address:
          type: string
          example: Avenida Queretaro
        zip_code:
          type: string
          example: '11590'
        phone_country_code:
          type: string
          example: '52'
        phone:
          type: string
          example: '5641663028'
        photo_id_country:
          type: string
          example: MEX
        photo_id_type:
          type: string
          example: GOV
        photo_id_number:
          type: string
          example: '2686505909'
        birth_country:
          type: string
          example: MEX
        date_of_birth:
          type: string
          format: date
          example: '1991-01-20'
        occupation:
          type: string
          example: EDUCATION
        purpose_of_transaction:
          type: string
          example: PERSONAL_USE
        relationship_to_sender:
          type: string
          example: FAMILY
        intended_use:
          type: string
          example: FAMILY_FRIENDS_SUPPORT
        id_state:
          type: string
          example: DF
        gender:
          type: string
          example: MALE
        id_expiration_year:
          type: string
          example: '2033'
        operator_name:
          type: string
          example: Daniel
        id_issue_year:
          type: string
          example: '2023'
    ReceiveReversalRequest:
      type: object
      required:
        - amount
        - reference
        - reversal_reason
      properties:
        amount:
          type: string
          example: '1596.00'
          description: The amount of the remittance to be reversed.
        reference:
          type: string
          example: '23033104'
          description: Reference number of the remittance transaction.
        reversal_reason:
          type: string
          enum:
            - WANTS_CASH
            - WRONG_TX
            - OUT_OF_CHECKS
            - ID_PROBLEM
          example: WRONG_TX
          description: Reason for reversing the remittance.
    CreateTransactionRequest:
      type: object
      properties:
        mgi_transaction_session_id:
          type: string
          example: 4200922151E1743120525540
        product_type:
          type: string
          example: RCV
    ReceiveRemittanceResponse:
      type: object
      properties:
        status:
          type: string
          example: available
        mgi_transaction_session_id:
          type: string
          example: 4200922151E1743121957877
        ready_for_commit:
          type: boolean
          example: true
    ReceiveReversalResponse:
      type: object
      properties:
        status:
          type: string
          example: reversed
          description: The status of the reversal.
        reversal_date_time:
          type: string
          format: date-time
          example: '2025-03-28T00:36:54.000Z'
          description: Timestamp of the reversal operation.
    RemittanceResponse:
      type: object
      properties:
        mgi_transaction_session_id:
          type: string
          example: 4200922151E1743120525540
        transaction_status:
          type: string
          example: AVAIL
        sender_first_name:
          type: string
          example: MARCOS
        sender_last_name:
          type: string
          example: DURAN
        sender_home_phone:
          type: string
          example: '967774185'
        receiver_first_name:
          type: string
          example: LUIS
        receiver_last_name:
          type: string
          example: MARTINEZ
        date_time_sent:
          type: string
          format: date-time
          example: '2025-03-14T15:06:08.887-05:00'
        receive_currency:
          type: string
          example: MXN
        receive_amount:
          type: string
          example: '1596.00'
        reference_number:
          type: string
          example: '23033104'
        originating_country:
          type: string
          example: USA
        indicative_receive_amount:
          type: string
          example: '0'
        indicative_exchange_rate:
          type: string
          example: '0.000000'
        original_send_amount:
          type: string
          example: '81.19'
        original_send_currency:
          type: string
          example: USD
        original_send_fee:
          type: string
          example: '3.81'
        original_exchange_rate:
          type: string
          example: '19.654979'
        ok_for_pickup:
          type: boolean
          example: true
        not_ok_for_pickup_reason_code:
          type: string
          example: '0'
        minutes_until_ok_for_pickup:
          type: string
          example: '0'
    CreateTransactionResponse:
      type: object
      properties:
        transaction_id:
          type: integer
          example: 132
        status:
          type: string
          example: received
        reference:
          type: string
          example: '23033104'
        transaction_date_time:
          type: string
          format: date-time
          example: '2025-03-28T00:31:58.206Z'
