openapi: 3.0.3
info:
  title: PagaSul API Reference
  description: |
    The PagaSul API lets you accept and disburse payments across Latin America
    through a single REST integration. All endpoints exchange JSON over HTTPS and
    each request is authenticated with a `signature` header.

    ## Base URLs

    | Environment | URL |
    | --- | --- |
    | Production | `https://api.pagasul.com` |
    | Checkout   | `https://checkout.pagasul.com` |

    ## Endpoints

    - **Pay-in** — initialize a payment and collect funds from a payer.
    - **Pay-out** — disburse funds to a recipient.
    - **Request for payment status** — check the current state of a payment.
    - **Confirmation** — submit confirmation data for payments that require an
      extra confirmation step.
    - **Balance** — retrieve your account balance.

    ## Conventions

    - `amount` fields are expressed in **major currency units** (e.g. `10.50`).
    - Each request carries a `signature` header. See the
      [Signature reference](/docs/reference/signature).
    - Payment states and result codes are listed in the
      [Statuses](/docs/reference/statuses) and [Callbacks](/docs/reference/callback)
      reference pages.

    The full machine-readable OpenAPI document for this server can be downloaded
    with the **Export** button above.
  version: 1.0.5
servers:
  - url: 'https://api.pagasul.com'
  - url: 'https://checkout.pagasul.com'
tags:
  - name: Pay-in
    description: Initialize payment
  - name: Pay-out
    description: Create a payout
  - name: Request for payment status
    description: Check the status of a payment
  - name: Confirmation
    description: Submit confirmation data for a payment that requires a confirmation step
  - name: Balance
    description: Retrieve account balance
paths:
  /v2/pay-in:
    servers:
      - url: 'https://api.pagasul.com'
    post:
      parameters:
        - in: header
          name: signature
          schema:
            type: string
            description: Signature string calculated
      tags:
        - Pay-in
      summary: Create a pay-in request
      requestBody:
        description: Initialize payment
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayInRequest'
        required: true
      responses:
        '200':
          description: Successful payment registration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatusResponse'
        '400':
          description: Invalid request format
        '401':
          description: Unauthorized or invalid request signature
        '500':
          description: Internal server error
      #callbacks:
      #inProgress:
      #'{$request.body#/payment_options.callback_url}':
      #post:
      #requestBody:
      #$ref: '#/components/schemas/PaymentStatusResponse'
      #responses:
      #'200':
      #description: OK
  /v2/pay-out:
    servers:
      - url: 'https://api.pagasul.com'
    post:
      parameters:
        - in: header
          name: signature
          schema:
            type: string
            description: Signature string calculated
      tags:
        - Pay-out
      summary: Create a pay-out request
      requestBody:
        description: Initialize payout
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayOutRequest'
        required: true
      responses:
        '200':
          description: Successful payment registration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayOutResponse'
        '400':
          description: Invalid request format
        '401':
          description: Unauthorized or invalid request signature
        '500':
          description: Internal server error
  #callbacks:
  #inProgress:
  #'{$request.body#/payment_options.callback_url}':
  #post:
  #requestBody:
  #$ref: '#/components/schemas/PaymentStatusResponse'
  #responses:
  #'200':
  #description: OK      
  /v2/status:
    servers:
      - url: 'https://api.pagasul.com'
    post:
      parameters:
        - in: header
          name: signature
          schema:
            type: string
            description: Signature string calculated
      tags:
        - Request for payment status
      summary: Create a request for the payment status
      requestBody:
        description: Check payment status
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
        required: true
      responses:
        '200':
          description: Successful request processing
          headers:
            signature:
              description: Signature string calculated
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatusResponse'
        '400':
          description: Invalid request format
        '401':
          description: Unauthorized or invalid request signature
        '500':
          description: Internal server error
  /v2/confirm:
    servers:
      - url: 'https://api.pagasul.com'
    post:
      parameters:
        - in: header
          name: signature
          schema:
            type: string
            description: Signature string calculated
      tags:
        - Confirmation
      summary: Confirm a payment
      description: Submit additional confirmation data for a payment that requires a confirmation step
      requestBody:
        description: Confirm a payment
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmRequest'
        required: true
      responses:
        '200':
          description: Successful confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatusResponse'
        '400':
          description: Invalid request format
        '401':
          description: Unauthorized or invalid request signature
        '500':
          description: Internal server error
  /v2/client_balance:
    servers:
      - url: 'https://api.pagasul.com'
    post:
      parameters:
        - in: header
          name: signature
          schema:
            type: string
            description: Signature string calculated
      tags:
        - Balance
      summary: Request the client balance
      description: Retrieve the current balance of your account per currency
      requestBody:
        description: Request the client balance
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceRequest'
        required: true
      responses:
        '200':
          description: Successful balance retrieval
          headers:
            signature:
              description: Signature string calculated
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '400':
          description: Invalid request format
        '401':
          description: Unauthorized or invalid request signature
        '500':
          description: Internal server error
components:
  schemas:
    PayInRequest:
      type: object
      required:
        - client_id
        - client_payment_id
        - amount
        - currency
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        client_payment_id:
          type: string
          description: Payment ID unique within your system
          example: payment_35
        payment_method:
          type: string
          description: Payment method's code to preselect a payment method on the checkout
          example: BR.PIX
          enum:
            - BR.PIX
            - AR.BT
            - AR.QR
            - CO.BT
            - CO.PSE
            - CO.NEQUI
            - CO.BC
            - CO.TF
            - CO.EF
            - CO.TP
            - CO.BREB
            - BO.BT
            - BO.QR
            - EC.BT
            - EC.CASH
            - EC.MOBILE
            - VE.BT
            - VE.PAGOMOVIL
        currency:
          type: string
          description: Code of the payment currency in the ISO-4217 alpha-3 format
          example: BRL
          enum:
            - BRL
            - ARS
            - COP
            - BOB
            - USD
            - VES
        amount:
          type: number
          description: Payment amount in major currency units
          example: 12.34
        reference:
          type: string
          description: Arbitrary reference or note you can attach to the payment
        payer:
          type: object
          required:
            - id
          description: Customer's data section
          properties:
            id:
              type: string
              description: Unique ID of the customer within your system
              example: customer_1234
            name:
              type: string
              description: Customer's full name
              example: John Doe
            email:
              type: string
              description: Customer's email
              example: johndoe@example.com
            country:
              type: string
              description: Customer's country in the ISO 3166-1 alpha-2 format
              example: BR
            state:
              type: string
              description: Customer's state
            city:
              type: string
              description: Customer's city
            address:
              type: string
              description: Customer's address
            phone:
              type: string
              description: Customer's phone
            language:
              type: string
              description: Customer's preferred language
              example: pt
            cpf:
              type: string
              description: Customer's CPF (Cadastro de Pessoas Físicas) for Brazilian payment methods
              example: 231.002.999-00
            cuit:
              type: string
              description: Customer's CUIT (Clave Única de Identificación Tributaria) for Argentinian payment methods
              example: 30-69330706-2
            citizenship_card:
              type: string
              description: Customer's citizenship card (Cédula de Ciudadanía) for Colombian payment methods
              example: 12.34.56.789
            nit:
              type: string
              description: Customer's NIT (Número de Identificación Tributaria) for Colombian payment methods
              example: 12.34.56.789
            is_trusted:
              type: boolean
              description: Set to true if the customer is already verified on your side
            first_name:
              type: string
              description: Customer's first name
            last_name:
              type: string
              description: Customer's last name
            middle_name:
              type: string
              description: Customer's middle name
            region:
              type: string
              description: Customer's region
            district:
              type: string
              description: Customer's district
            street:
              type: string
              description: Customer's street
            building:
              type: string
              description: Customer's building
            zip:
              type: string
              description: Customer's postal/ZIP code
            birthdate:
              type: string
              description: Customer's date of birth
            ip_address:
              type: string
              description: Customer's IP address
            document:
              type: string
              description: Customer's generic identification document number
            ce:
              type: string
              description: Customer's Cédula de Extranjería for Colombian payment methods
            ci:
              type: string
              description: Customer's Cédula de Identidad
            ti:
              type: string
              description: Customer's Tarjeta de Identidad for Colombian payment methods
            pas:
              type: string
              description: Customer's passport number
            ruc:
              type: string
              description: Customer's RUC (Registro Único de Contribuyentes) for Ecuadorian/Peruvian payment methods
            rif:
              type: string
              description: Customer's RIF (Registro de Información Fiscal) for Venezuelan payment methods
        payer_account:
          type: object
          description: Customer's account data
          properties:
            bank_code:
              type: string
              description: Customer's bank code
        payment_options:
          type: object
          description: Optional section for extra parameters used for payment flow adjustment
          properties:
            return_url:
              type: string
              description: The URL to redirect the customer to after the payment is completed
            callback_url:
              type: string
              description: 'The URL to send callbacks to. If not passed, callbacks will be sent to the URL you provided PagaSul with when integrating'
            allow_amount_change:
              type: boolean
              description: Whether the customer is allowed to change the amount on the checkout page
            is_test:
              type: boolean
              description: Marks the payment as a test payment
    PayOutRequest:
      type: object
      required:
        - client_id
        - client_payment_id
        - payment_method
        - amount
        - currency
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        client_payment_id:
          type: string
          description: Payment ID unique within your system
          example: payment_35
        payment_method:
          type: string
          description: Payment method's code
          example: BR.PIX
          enum:
            - BR.PIX
            - AR.BT
            - AR.QR
            - CO.BT
            - CO.PSE
            - CO.NEQUI
            - CO.BC
            - CO.TF
            - CO.EF
            - CO.TP
            - CO.BREB
            - BO.BT
            - BO.QR
            - EC.BT
            - EC.CASH
            - EC.MOBILE
            - VE.BT
            - VE.PAGOMOVIL
        currency:
          type: string
          description: Code of the pay-out currency in the ISO-4217 alpha-3 format
          example: BRL
          enum:
            - BRL
            - ARS
            - COP
            - BOB
            - USD
            - VES
        amount:
          type: number
          description: Pay-out amount in major currency units
          example: 12.34
        reference:
          type: string
          description: Arbitrary reference or note you can attach to the pay-out
        payee:
          type: object
          required:
            - id
          description: Customer's data section
          properties:
            id:
              type: string
              description: Unique ID of the customer within your system
              example: customer_1234
            name:
              type: string
              description: Customer's full name
              example: John Doe
            email:
              type: string
              description: Customer's email
              example: johndoe@example.com
            country:
              type: string
              description: Customer's country in the ISO 3166-1 alpha-2 format
              example: BR
            state:
              type: string
              description: Customer's state
            city:
              type: string
              description: Customer's city
            address:
              type: string
              description: Customer's address
            phone:
              type: string
              description: Customer's phone
            language:
              type: string
              description: Customer's preferred language
              example: pt
            cpf:
              type: string
              description: Customer's CPF (Cadastro de Pessoas Físicas) for Brazilian payment methods
              example: 231.002.999-00
            cuit:
              type: string
              description: Customer's CUIT (Clave Única de Identificación Tributaria) for Argentinian payment methods
              example: 30-69330706-2
            citizenship_card:
              type: string
              description: Customer's citizenship card (Cédula de Ciudadanía) for Colombian payment methods
              example: 12.34.56.789
            nit:
              type: string
              description: Customer's NIT (Número de Identificación Tributaria) for Colombian payment methods
              example: 12.34.56.789
            is_trusted:
              type: boolean
              description: Set to true if the customer is already verified on your side
            first_name:
              type: string
              description: Customer's first name
            last_name:
              type: string
              description: Customer's last name
            middle_name:
              type: string
              description: Customer's middle name
            region:
              type: string
              description: Customer's region
            district:
              type: string
              description: Customer's district
            street:
              type: string
              description: Customer's street
            building:
              type: string
              description: Customer's building
            zip:
              type: string
              description: Customer's postal/ZIP code
            birthdate:
              type: string
              description: Customer's date of birth
            ip_address:
              type: string
              description: Customer's IP address
            document:
              type: string
              description: Customer's generic identification document number
            ce:
              type: string
              description: Customer's Cédula de Extranjería for Colombian payment methods
            ci:
              type: string
              description: Customer's Cédula de Identidad
            ti:
              type: string
              description: Customer's Tarjeta de Identidad for Colombian payment methods
            pas:
              type: string
              description: Customer's passport number
            ruc:
              type: string
              description: Customer's RUC (Registro Único de Contribuyentes) for Ecuadorian/Peruvian payment methods
            rif:
              type: string
              description: Customer's RIF (Registro de Información Fiscal) for Venezuelan payment methods
        payee_account:
          type: object
          description: Customer's account data
          properties:
            pix_key:
              type: string
              description: 'Customer''s key for the Pix account. It may be the cusomer''s CPF, CNPJ, email, phone, or EVP'
              example: johndoe@example.com
            pix_key_type:
              type: string
              description: Type of the customer's Pix key
              example: EMAIL
              enum:
                - CPF
                - CNPJ
                - EMAIL
                - PHONE
                - EVP
            account_type:
              type: string
              description: Customer's bank account type
              example: CACC
              enum:
                - CACC
                - SVGS
            number:
              type: string
              description: Customer's bank account number
              example: 11-342-3
            bank_code:
              type: string
              description: Customer's bank code
              example: CO.BDNEQ
            holder_name:
              type: string
              description: Bank account's holder name
              example: John Doe
        payment_options:
          type: object
          description: Optional section for extra parameters used for payment flow adjustment
          properties:
            callback_url:
              type: string
              description: 'The URL to send callbacks to. If not passed, callbacks will be sent to the URL you provided PagaSul with when integrating'
            allow_amount_change:
              type: boolean
              description: Whether the amount is allowed to change during processing
            is_test:
              type: boolean
              description: Marks the pay-out as a test operation
    StatusRequest:
      type: object
      required:
        - client_id
      anyOf:
        - required:
            - client_payment_id
        - required:
            - payment_id
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        client_payment_id:
          type: string
          description: Payment ID unique within your system
          example: payment_35
        payment_id:
          type: integer
          format: uint64
          description: Payment ID you received from PagaSul in the response to your initial payment request
          example: 246001234
    PaymentStatusResponse:
      type: object
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        client_payment_id:
          type: string
          description: Payment ID unique within your system
          example: payment_35
        payment_id:
          type: integer
          format: uint64
          description: Payment ID the PagaSul payment platform assigned to the payment
          example: 246001234
        status:
          type: string
          description: Status the payment is currently in
          example: success
          enum:
            - new
            - redirect
            - processing
            - success
            - decline
            - failed
        payment_method:
          type: string
          description: Payment method's code
          example: BR.PIX
          enum:
            - BR.PIX
            - AR.BT
            - AR.QR
            - CO.BT
            - CO.PSE
            - CO.NEQUI
            - CO.BC
            - CO.TF
            - CO.EF
            - CO.TP
            - CO.BREB
            - BO.BT
            - BO.QR
            - EC.BT
            - EC.CASH
            - EC.MOBILE
            - VE.BT
            - VE.PAGOMOVIL
        payment_type:
          type: string
          description: Payment method's type
          example: pay-in
        currency:
          type: string
          description: Code of the payment currency in the ISO-4217 alpha-3 format
          example: BRL
          enum:
            - BRL
            - ARS
            - COP
            - BOB
            - USD
            - VES
        amount:
          type: number
          description: Payment amount in major currency units
          example: 12.34
        checkout_data:
          type: object
          description: Data you should use to redirect the customer
          properties:
            url:
              type: string
              description: URL to redirect the customer to
              example: 'https://example.com/redirect'
            method:
              type: string
              description: HTTP method for retrieving the checkout page
              example: GET
        result_code:
          type: string
          description: Internal result code of request processing
          example: OK
          enum:
            - OK
            - BAD REQUEST
            - NOT FOUND
            - NOT CREATED
        result_message:
          type: string
          description: Description of the result code
          example: unauthorized
    PayOutResponse:
      type: object
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        client_payment_id:
          type: string
          description: Payment ID unique within your system
          example: payment_35
        payment_id:
          type: integer
          format: uint64
          description: Payment ID the PagaSul payment platform assigned to the payment
          example: 246001234
        status:
          type: string
          description: Status the pay-out is currently in
          example: new
          enum:
            - new
            - processing
            - success
            - decline
            - failed
        payment_method:
          type: string
          description: Payment method's code
          example: BR.PIX
          enum:
            - BR.PIX
            - AR.BT
            - AR.QR
            - CO.BT
            - CO.PSE
            - CO.NEQUI
            - CO.BC
            - CO.TF
            - CO.EF
            - CO.TP
            - CO.BREB
            - BO.BT
            - BO.QR
            - EC.BT
            - EC.CASH
            - EC.MOBILE
            - VE.BT
            - VE.PAGOMOVIL
        payment_type:
          type: string
          description: Payment method's type
          example: pay-out
        currency:
          type: string
          description: Code of the pay-out currency in the ISO-4217 alpha-3 format
          example: BRL
          enum:
            - BRL
            - ARS
            - COP
            - BOB
            - USD
            - VES
        amount:
          type: number
          description: Pay-out amount in major currency units
          example: 12.34
        result_code:
          type: string
          description: Internal result code of request processing
          example: OK
          enum:
            - OK
            - BAD REQUEST
            - NOT FOUND
            - NOT CREATED
        result_message:
          type: string
          description: Description of the result code
          example: payment processing
    ConfirmRequest:
      type: object
      required:
        - client_id
        - client_payment_id
        - confirmation_data
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        client_payment_id:
          type: string
          description: Payment ID unique within your system
          example: payment_35
        confirmation_data:
          type: object
          description: Free-form object with the confirmation data required by the payment method
          additionalProperties: true
    BalanceRequest:
      type: object
      required:
        - client_id
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        datetime:
          type: string
          description: Point in time to get the balance snapshot for. If not passed, the current balance is returned
    BalanceResponse:
      type: object
      properties:
        client_id:
          type: integer
          example: 123
          description: Account ID you obtained from PagaSul when integrating
        balance:
          type: array
          description: Balance per currency
          items:
            type: object
            properties:
              currency:
                type: string
                description: Code of the currency in the ISO-4217 alpha-3 format
                example: BRL
              amount:
                type: number
                description: Balance amount in major currency units
                example: 1234.56
        result_code:
          type: string
          description: Internal result code of request processing
          example: OK
        result_message:
          type: string
          description: Description of the result code
          example: OK
