openapi: 3.0.3
info:
  title: Apurata aCuotaz POS REST config orders API
  version: '1.0'
  x-apievangelist-generated: '2026-07-18'
  x-apievangelist-method: generated
  x-apievangelist-source: https://docs.apurata.com/POS/rest_api/
  description: Merchant-facing REST API for the aCuotaz "buy now, pay later" installment financing product operated by Apurata (Tecno Creditos S.A.C., Peru). Lets an e-commerce merchant fetch financing limits, create and manage installment orders, confirm/cancel orders, issue total or partial refunds, and render the aCuotaz checkout widgets. Transcribed faithfully from the public documentation at docs.apurata.com; not published by Apurata as an OpenAPI file.
  contact:
    name: Apurata aCuotaz Integrations
    url: https://docs.apurata.com/POS/intro/
  license:
    name: Proprietary
servers:
- url: https://apurata.com
  description: Production (test and live behavior are selected by the client_id / secret token issued)
tags:
- name: orders
  description: Order lifecycle (create, read, confirm, cancel)
paths:
  /pos/order/create:
    post:
      tags:
      - orders
      operationId: createOrder
      summary: Create order
      description: 'Create a new aCuotaz installment order. Idempotent on order_id: submitting an existing order_id returns the existing order with status "already_created" instead of creating a duplicate.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Order created or already existed
          content:
            application/json:
              schema:
                type: object
                properties:
                  redirect_to:
                    type: string
                    format: uri
                  status:
                    type: string
                    enum:
                    - new_order
                    - already_created
        '400':
          description: Validation error or client registration issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Token validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
  /pos/order/{order_id}:
    get:
      tags:
      - orders
      operationId: getOrder
      summary: Get order information
      description: Retrieve the current status and details of an order, including a magic continuation link.
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
  /pos/order/{order_id}/cancel:
    post:
      tags:
      - orders
      operationId: cancelOrder
      summary: Cancel order
      description: Cancel an order that has not yet been confirmed/funded.
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cancel result
          content:
            application/json:
              schema:
                type: object
                properties:
                  modified_orders:
                    type: integer
        '400':
          description: Confirmed order cannot be canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
  /pos/order/{order_id}/confirm:
    post:
      tags:
      - orders
      operationId: confirmOrder
      summary: Confirm order
      description: Confirm an approved and funded order so the merchant fulfills the purchase.
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Confirm result
          content:
            application/json:
              schema:
                type: object
                properties:
                  modified_orders:
                    type: integer
        '400':
          description: Order not in an approvable/funded state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
components:
  schemas:
    OrderStatus:
      type: string
      enum:
      - initial
      - created
      - approved
      - onhold
      - validated
      - funded
      - rejected
      - canceled
    Order:
      type: object
      properties:
        order_id:
          type: string
        amount:
          type: number
          format: float
        status:
          $ref: '#/components/schemas/OrderStatus'
        magic_link:
          type: string
          format: uri
        pos_client_id:
          type: string
        customer_data:
          type: object
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    CreateOrderRequest:
      type: object
      required:
      - amount
      - order_id
      - pos_client_id
      - url_redir_on_canceled
      - url_redir_on_rejected
      - url_redir_on_success
      - url_redir_on_downpayment
      properties:
        amount:
          type: number
          format: float
        order_id:
          type: string
          description: Merchant-unique order id (idempotency key)
        pos_client_id:
          type: string
        url_redir_on_canceled:
          type: string
          format: uri
        url_redir_on_rejected:
          type: string
          format: uri
        url_redir_on_success:
          type: string
          format: uri
        url_redir_on_downpayment:
          type: string
          format: uri
        acuotaz_send_sms:
          type: boolean
        expiration_ts:
          type: string
          description: UTC-0 timestamp YYYY-MM-DD hh:mm:ss.mmm
        description:
          type: string
        url_redir_on_order_detail:
          type: string
          format: uri
        customer_6m_payment:
          type: number
          format: float
        customer_data:
          type: object
        financed_products:
          type: array
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Secret token issued by Apurata, sent as Authorization: Bearer <secret_token>. HTTPS is mandatory.'