---
title: "Create preauthorization"
method: POST
path: "/smart-transfers/preauthorizations"
tags: ["Smart Transfer"]
---

# Create preauthorization

`POST /smart-transfers/preauthorizations`

Creates the smart transfer preauthorization resource

## Request body

- CreateSmartTransferPreauthorization — Create smart transfer preauthorization request data
  - `connectorId` number, required — Primary identifier of the connector
  - `parameters` SmartTransferPreauthorizationParameter, required — Credentials neccesary to create a smart transfer preauthorization
    - `cpf` string, required — CPF of the payer
    - `cnpj` string — CNPJ of the payer
  - `recipientIds` string[], required
  - `callbackUrls` SmartTransferCallbackUrls — Redirect urls after the preauthorization flow was completed or ended in error status
    - `success` string — Url to be redirected after the preauthorization was completed
    - `error` string — Url to be redirected after the preauthorization ended in error status
  - `clientPreauthorizationId` string — Client preauthorization identifier
  - `configuration` SmartTransferPreauthorizationConfiguration — Smart transfer preauthorization configuration
    - `totalAllowedAmount` number — Maximum amount to be reached by the sum of all transactions that use the consent authorized by the customer.
    - `transactionLimit` number — Maximum amount for each payment transaction associated with this consent.
    - `periodicLimits` SmartTransferPreauthorizationConfigurationPeriodicLimits — Transactional limits per period as determined by the paying user.
      - `day` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
      - `week` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
      - `month` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
      - `year` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.

## Response `200`

Create a Smart Transfer Preauthorization.

- SmartTransferPreauthorization — Smart transfer preauthorization
  - `id` string, required — Preauthorization primary identifier
  - `status` 'CREATED' | 'COMPLETED' | 'REVOKED' | 'REJECTED' | 'ERROR', required — Preauthorization lifecycle status. - `CREATED`: the preauthorization was created and is awaiting the payer's consent (see `consentUrl`). - `COMPLETED`: the payer authorized the consent. The preauthorization can now be used to execute payments. - `REJECTED`: the payer rejected the consent. - `REVOKED`: the consent was revoked after being authorized. - `ERROR`: the preauthorization flow failed unexpectedly (see `errorDetail`).
  - `consentUrl` string — Url to give the consent in the institution
  - `clientPreauthorizationId` string — Client preauthorization identifier
  - `callbackUrls` SmartTransferCallbackUrls — Redirect urls after the preauthorization flow was completed or ended in error status
    - `success` string — Url to be redirected after the preauthorization was completed
    - `error` string — Url to be redirected after the preauthorization ended in error status
  - `recipients` PaymentRecipient[], required
    - `type` 'BANK_ACCOUNT', required — Recipient discriminator. Always `BANK_ACCOUNT` for this schema.
    - `id` string, required — Primary identifier
    - `taxNumber` string, required — Account owner tax number. Can be CPF or CNPJ (only numbers).
    - `name` string, required — Account owner name.
    - `paymentInstitution` PaymentInstitution, required — Response with information related to a payment institution
      - `id` string, required — Primary identifier
      - `name` string, required — Payment institution name
      - `tradeName` string, required — Payment institution trade name
      - `ispb` string, required — Payment institution ISPB
      - `compe` string — Payment institution COMPE
      - `createdAt` string, date-time, required — Date when the payment institution was created
      - `updatedAt` string, date-time, required — Date when the payment institution was updated
    - `isDefault` boolean, required — Indicates if the recipient is the default one
    - `account` PaymentRecipientAccount, required — Payment receiver bank account information
      - `branch` string, required — Receiver bank account branch (agency)
      - `number` string, required — Receiver bank account number
      - `type` string, required — Receiver bank account type, could be: 'CHECKING_ACCOUNT', 'SAVINGS_ACCOUNT' or 'GUARANTEED_ACCOUNT'
    - `pixKey` string — Pix key associated with the payment recipient
    - `createdAt` string, date-time, required — Date when the payment recipient was created
    - `updatedAt` string, date-time, required — Date when the payment recipient was last updated
  - `connector` Connector, required — Connector object
    - `id` number, required — Primary identifier
    - `name` string — Name of the institution
    - `institutionUrl` string — Homepage of the institution
    - `imageUrl` string — Image of the logo hosted by Pluggy
    - `primaryColor` string — Primary color
    - `type` string — Type of institution
    - `country` string — Country located
    - `credentials` ConnectorCredential[] — Parameters required to start the connection
      - `name` string, required — Name of the key
      - `label` string, required — Label for input
      - `type` 'text' | 'password' | 'number' | 'image' | 'select', required — Type of credential required
      - `assistiveText` string — Text to help the user when completing the input
      - `data` string — Used to return base64 images
      - `placeholder` string — Placeholder text for the input
      - `validation` string — Regex validation for the user's input
      - `validationMessage` string — Validation message when input doesn't match the regex
      - `mfa` boolean — Credential is an MFA parameter and must be refreshed on each execution
      - `options` CredentialSelectOption[] — List of possible values for the input
        - `value` string, required — Value for the option
        - `label` string, required — Label for the option
    - `hasMFA` boolean — Does the connector require an MFA to execute?
    - `products` string[] — Products supported by the connector
    - `oauth` boolean — If 'true', the connector requires an Oauth flow to execute
    - `oauthUrl` string — URL to perform Oauth flow if needed
    - `resetPasswordUrl` string — URL to the financial institution to reset the password
    - `health` ConnectorHealth — Connector health status
      - `status` string — 'ONLINE' | 'OFFLINE' | 'UNSTABLE'
      - `stage` string
      - `details` object — Statistics about your recent connections on the connector and recent connection rate (percentage of healthy connections). This field is only present if you include the parameter healthDetails=true. This will be null if there was an error obtaining health details.
        - `connectionRateLast6Hours` number — A number from 0 to 100: the percentage of executions that succesfully connect to the institution: status of CONNECTION_ERROR,ERROR,SITE_NOT_AVAILABLE decrease the percentage. Any other status (like SUCCESS/LOGIN_ERROR) increase the percentage. The value will be null if there were no connections
        - `connectionsLast6Hours` number — Amount of your connections for this connector during the last 6 hours. 0 if there were no connections
    - `isOpenFinance` boolean — Indicates if the connector uses the regulated Open Finance APIs
    - `supportsPaymentInitiation` boolean — Indicates if the connector supports the payment initiation API
    - `supportsScheduledPayments` boolean — Indicates if the connector supports scheduled payments
    - `supportsSmartTransfers` boolean — Indicates if the connector supports smart transfers
    - `supportsBoletoManagement` boolean — Indicates if the connector supports boleto management
    - `supportsAutomaticPix` boolean — Indicates if the connector supports automatic Pix
    - `createdAt` string, date-time — Date of creation
    - `updatedAt` string, date-time — Date of last modification
  - `createdAt` string, date-time, required — Date when the preauthorization was created
  - `updatedAt` string, date-time, required — Date when the preauthorization was updated
  - `configuration` SmartTransferPreauthorizationConfiguration — Smart transfer preauthorization configuration
    - `totalAllowedAmount` number — Maximum amount to be reached by the sum of all transactions that use the consent authorized by the customer.
    - `transactionLimit` number — Maximum amount for each payment transaction associated with this consent.
    - `periodicLimits` SmartTransferPreauthorizationConfigurationPeriodicLimits — Transactional limits per period as determined by the paying user.
      - `day` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
      - `week` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
      - `month` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
      - `year` SmartTransferPreauthorizationConfigurationPeriodicLimit — Transactional limit per period. If sent, at least one of the fields (quantityLimit or transactionLimit) must be filled in.
        - `quantityLimit` number — Maximum number of transactions allowed to occur in the period.
        - `transactionLimit` number — Maximum amount to be transacted in the period.
  - `errorDetail` object — Error detail
    - `code` string — Error code
    - `description` string — Error description
    - `detail` string — Error detail

## Other responses

- `400` — Preauthorization is Invalid

---

[API](https://skmtc.dev/pluggy/apis/pluggy-api.md) · [All operations](https://skmtc.dev/pluggy/apis/pluggy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pluggy/pluggy-api/revisions/75e87ec7f9cd/schema)