openapi: 3.1.0
info:
  description: Binco Backend B2B API
  version: 0.0.1
  title: Binco Backend B2B API
  contact:
    email: integrations@binco.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: Merchant
  - name: Payment Intent
security:
  - BusinessAuth: []
  - MerchantAuth: []
paths:
  /b2b/countries:
    get:
      tags:
        - Merchant
      summary: Get merchant countries
      description: Retrieve the countries where the merchant can operate, and details about the payment methods available in each country.
      security:
        - MerchantAuth: []
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetMerchantCountriesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UnauthorizedError"
                  - $ref: "#/components/schemas/BadApiKeyError"
                  - $ref: "#/components/schemas/BadSignatureError"
        "500":
          description: Error processing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorProcessingRequest"
  /b2b/countries/{countryCode}:
    get:
      tags:
        - Merchant
      summary: Get merchant country details
      description: Retrieve the requested country, and details about the payment methods available in it if available.
      security:
        - MerchantAuth: []
      parameters:
        - name: countryCode
          in: path
          required: true
          description: The country code of the country
          schema:
            $ref: "#/components/schemas/Country"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetMerchantCountriesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UnauthorizedError"
                  - $ref: "#/components/schemas/BadApiKeyError"
                  - $ref: "#/components/schemas/BadSignatureError"
        "404":
          description: Country not available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountryNotAvailable"
        "500":
          description: Error processing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorProcessingRequest"
  /b2b/merchants/{merchantId}/countries:
    get:
      tags:
        - Merchant
      summary: Get merchant countries
      description: Retrieve the countries where the merchant can operate, and details about the payment methods available in each country.
      security:
        - BusinessAuth: []
        - MerchantAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The id of the merchant
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetMerchantCountriesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UnauthorizedError"
                  - $ref: "#/components/schemas/BadApiKeyError"
                  - $ref: "#/components/schemas/BadSignatureError"
        "500":
          description: Error processing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorProcessingRequest"
  /b2b/merchants/{merchantId}/countries/{countryCode}:
    get:
      tags:
        - Merchant
      summary: Get merchant country details
      description: Retrieve the requested country, and details about the payment methods available in it if available.
      security:
        - BusinessAuth: []
        - MerchantAuth: []
      parameters:
        - name: countryCode
          in: path
          required: true
          description: The country code of the country
          schema:
            $ref: "#/components/schemas/Country"
        - name: merchantId
          in: path
          required: true
          description: The id of the merchant
          schema:
            type: string
            format: uuid
      responses:
  /b2b/payment-intents:
    get:
      tags:
        - Payment Intent
      summary: Get payment intents
      description: Returns the payment intents of the business
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetPaymentIntentsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UnauthorizedError"
                  - $ref: "#/components/schemas/BadApiKeyError"
                  - $ref: "#/components/schemas/BadSignatureError"
        "500":
          description: Error processing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorProcessingRequest"
    post:
      tags:
        - Payment Intent
      summary: Create payment intent
      description: Create payment intent for the specified merchant.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentIntentRequest"
        description: Payment intent request data
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIntentDTO"
        "400":
          description: Invalid VAT percentage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidVATPercentage"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UnauthorizedError"
                  - $ref: "#/components/schemas/BadApiKeyError"
                  - $ref: "#/components/schemas/BadSignatureError"
        "404":
          description: Payment method not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentMethodNotFound"
        "500":
          description: Error processing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorProcessingRequest"
  /b2b/payment-intents/{paymentIntentId}:
    get:
      tags:
        - Payment Intent
      summary: Get payment intent details
      description: Retrieve the requested payment intent.
      parameters:
        - name: paymentIntentId
          in: path
          required: true
          description: The id of the payment intent
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIntentDTO"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UnauthorizedError"
                  - $ref: "#/components/schemas/BadApiKeyError"
                  - $ref: "#/components/schemas/BadSignatureError"
        "404":
          description: Payment intent not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIntentNotFound"
        "500":
          description: Error processing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorProcessingRequest"
servers:
  - url: https://payins-sandbox.binco.io/api/v1
    description: Sandbox server
components:
  securitySchemes:
    BusinessAuth:
      type: apiKey
      in: header
      name: api-key
      description: >
        Use the api-key and signature headers to authenticate requests for the Business entity.
        The signature should be encrypted with HMAC-SHA256 using the api-secret.
        These credentials can be obtained by registering through the Business authentication API.
    MerchantAuth:
      type: apiKey
      in: header
      name: api-key
      description: >
        Use the api-key and signature headers to authenticate requests for the Merchant entity.
        The signature should be encrypted with HMAC-SHA256 using the api-secret.
        These credentials can be obtained by registering through the Merchant authentication API.

  schemas:
    Country:
      type: string
      enum:
        - ARG
        - BRA
        - URY
    Currency:
      type: string
      enum:
        - ARS
        - BRL
        - CLP
        - COP
        - MXN
        - PEN
        - PYG
        - USD
        - UYU
    GetMerchantCountriesResponse:
      type: object
      properties:
        merchant:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        countries:
          type: array
          items:
            $ref: "#/components/schemas/CountryWithPaymentMethodInfo"
    UnauthorizedError:
      type: object
      properties:
        errorCode:
          type: number
          examples: [4000]
        message:
          type: string
          examples: [Unauthorized]
    BadApiKeyError:
      type: object
      properties:
        errorCode:
          type: number
          examples: [4001]
        message:
          type: string
          examples: [Bad API key]
    BadSignatureError:
      type: object
      properties:
        errorCode:
          type: number
          examples: [4002]
        message:
          type: string
          examples: [Bad signature]
    ErrorProcessingRequest:
      type: object
      properties:
        errorCode:
          type: number
          examples: [1003]
        message:
          type: string
          examples: [Error processing request]
    PaymentMethodOptions:
      type: object
      properties:
        networks:
          type: array
          items:
            type: string
            examples: ["VISA", "MASTERCARD"]
    PaymentMethodRequestInfo:
      type: object
      properties:
        name:
          type: string
          examples: ["CREDIT_CARD"]
        options:
          $ref: "#/components/schemas/PaymentMethodOptions"
    PaymentMethodData:
      type: object
      properties:
        name:
          type: string
          examples: ["CREDIT_CARD"]
        currencies:
          type: array
          items:
            $ref: "#/components/schemas/Currency"
        options:
          $ref: "#/components/schemas/PaymentMethodOptions"
    CountryWithPaymentMethodInfo:
      type: object
      properties:
        country:
          $ref: "#/components/schemas/Country"
        currencies:
          type: array
          items:
            $ref: "#/components/schemas/Currency"
        vat:
          type: array
          items:
            type: number
            examples: [0, 20, 22]
        paymentMethods:
          type: array
          items:
            $ref: "#/components/schemas/PaymentMethodData"
    CountryNotAvailable:
      type: object
      properties:
        errorCode:
          type: number
          examples: [6000]
        message:
          type: string
          examples: [Country not available]
    PaymentIntentType:
      type: string
      enum:
        - ECO
    PaymentIntentStatus:
      type: string
      enum:
        - PAYMENT_METHOD_PENDING
        - REQUIRES_CONFIRMATION
        - REQUIRES_ACTION
        - PENDING
        - SUCCESSFUL
        - REFUNDED
        - REFUND_FAILED
        - REFUND_PENDING
        - REFUND_REJECTED
    NextActionType:
      type: string
      enum:
        - REDIRECT
        - DISPLAY_QR
    NextActionRedirect:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/NextActionType"
        redirect:
          type: object
          properties:
            url:
              type: string
              examples:
                ["https://payins-sandbox.binco.io/api/v1/next-action/redirect"]
            reference:
              type: string
              examples: ["1025a9bb-3d83-4fba-af77-7a03305cf798"]
    NextActionQR:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/NextActionType"
        qr:
          type: object
          properties:
            image:
              type: string
            code:
              type: string
            expiration:
              type: object
              properties:
                date:
                  type: string
                time:
                  type: string
                dateTimeUTC:
                  type: string
    PaymentIntentDTO:
      type: object
      properties:
        paymentIntentId:
          type: string
          format: uuid
          examples: ["581555e2-a6b3-491a-a53d-1889417293ca"]
        merchant:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        type:
          $ref: "#/components/schemas/PaymentIntentType"
        externalReference:
          type: string
          examples: ["externalReference123"]
        description:
          type: string
          examples: ["Payment for order 123"]
        currency:
          $ref: "#/components/schemas/Currency"
        amount:
          type: number
          examples: [100]
        amountDetails:
          type: object
          properties:
            tip:
              type: number
              examples: [10]
            vatAmount:
              type: number
              examples: [20]
        invoiceDetails:
          type: object
          properties:
            reference:
              type: string
              examples: ["invoiceReference"]
            serie:
              type: string
              examples: ["invoiceSerie"]
            number:
              type: number
              examples: [123]
        includeAllPaymentMethods:
          type: boolean
          examples: [false]
        paymentMethod:
          $ref: "#/components/schemas/PaymentMethodData"
        availablePaymentMethods:
          type: array
          items:
            $ref: "#/components/schemas/PaymentMethodData"
        status:
          type: object
          properties:
            code:
              $ref: "#/components/schemas/PaymentIntentStatus"
            description:
              type: string
              examples: ["The payment is pending."]
        createdAt:
          type: string
        nextAction:
          oneOf:
            - $ref: "#/components/schemas/NextActionRedirect"
            - $ref: "#/components/schemas/NextActionQR"
    PaymentIntentNotFound:
      type: object
      properties:
        errorCode:
          type: number
          examples: [7000]
        message:
          type: string
          examples: [Payment intent not found]
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
        pageSize:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    GetPaymentIntentsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/PaymentIntentDTO"
        pagination:
          $ref: "#/components/schemas/Pagination"
    PaymentIntentRequest:
      type: object
      properties:
        merchantId:
          type: string
          format: uuid
        type:
          $ref: "#/components/schemas/PaymentIntentType"
        externalReference:
          type: string
          examples: ["externalReference123"]
        description:
          type: string
          examples: ["Payment for order 123"]
        countryCode:
          $ref: "#/components/schemas/Country"
        currency:
          $ref: "#/components/schemas/Currency"
        amount:
          type: number
          examples: [100]
        amountDetails:
          type: object
          properties:
            tip:
              type: number
              examples: [10]
            vatAmount:
              type: number
              examples: [20]
        invoiceDetails:
          type: object
          properties:
            reference:
              type: string
              examples: ["invoiceReference"]
            serie:
              type: string
              examples: ["invoiceSerie"]
            number:
              type: number
              examples: [123]
        includeAllPaymentMethods:
          type: boolean
          examples: [false]
        paymentMethods:
          $ref: "#/components/schemas/PaymentMethodRequestInfo"
        redirectUrl:
          type: string
          examples: ["https://business-site/process-payment-intent"]
    PaymentMethodNotFound:
      type: object
      properties:
        errorCode:
          type: number
          examples: [7001]
        message:
          type: string
          examples: [Payment method not found]
        data:
          type: string
          examples: ["Missing payment methods: CREDIT_CARD"]
    InvalidVATPercentage:
      type: object
      properties:
        errorCode:
          type: number
          examples: [7002]
        message:
          type: string
          examples: [Invalid VAT percentage]
        data:
          type: string
          examples: ["The allowed VAT percentages for the country are: 22, 10, 0"]
