POST/smart-transfers/preauthorizations

Create preauthorization

Creates the smart transfer preauthorization resource

Request Body

required

object

Create smart transfer preauthorization request data

connectorIdrequirednumber

Primary identifier of the connector

parametersrequiredobject

Credentials neccesary to create a smart transfer preauthorization

cpfrequiredstring

CPF of the payer

cnpjstring

CNPJ of the payer

recipientIdsrequiredstring[]

itemsstring

Primary identifier of the payment recipient

callbackUrlsobject

Redirect urls after the preauthorization flow was completed or ended in error status

successstring

Url to be redirected after the preauthorization was completed

errorstring

Url to be redirected after the preauthorization ended in error status

clientPreauthorizationIdstring

Client preauthorization identifier

configurationobject

Smart transfer preauthorization configuration

totalAllowedAmountnumber

Maximum amount to be reached by the sum of all transactions that use the consent authorized by the customer.

transactionLimitnumber

Maximum amount for each payment transaction associated with this consent.

periodicLimitsobject

Transactional limits per period as determined by the paying user.

Responses

200Create a Smart Transfer Preauthorization.

object

Smart transfer preauthorization

idrequiredstring

Preauthorization primary identifier

statusrequiredstring

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`).

CREATEDCOMPLETEDREVOKEDREJECTEDERROR

consentUrlstring

Url to give the consent in the institution

clientPreauthorizationIdstring

Client preauthorization identifier

callbackUrlsobject

Redirect urls after the preauthorization flow was completed or ended in error status

successstring

Url to be redirected after the preauthorization was completed

errorstring

Url to be redirected after the preauthorization ended in error status

recipientsrequiredobject[]

itemsobject

Bank-account payment recipient. Returned by `/payments/recipients` endpoints and embedded inside payment requests when the request targets a registered recipient.

connectorrequiredobject

Connector object

idrequirednumber (integer)

Primary identifier

namestring

Name of the institution

institutionUrlstring

Homepage of the institution

imageUrlstring

Image of the logo hosted by Pluggy

primaryColorstring

Primary color

typestring

Type of institution

countrystring

Country located

credentialsobject[]

Parameters required to start the connection

hasMFAboolean

Does the connector require an MFA to execute?

productsstring[]

Products supported by the connector

oauthboolean

If 'true', the connector requires an Oauth flow to execute

oauthUrlstring

URL to perform Oauth flow if needed

resetPasswordUrlstring

URL to the financial institution to reset the password

healthobject

Connector health status

isOpenFinanceboolean

Indicates if the connector uses the regulated Open Finance APIs

supportsPaymentInitiationboolean

Indicates if the connector supports the payment initiation API

supportsScheduledPaymentsboolean

Indicates if the connector supports scheduled payments

supportsSmartTransfersboolean

Indicates if the connector supports smart transfers

supportsBoletoManagementboolean

Indicates if the connector supports boleto management

supportsAutomaticPixboolean

Indicates if the connector supports automatic Pix

createdAtstring (date-time)

Date of creation

updatedAtstring (date-time)

Date of last modification

createdAtrequiredstring (date-time)

Date when the preauthorization was created

updatedAtrequiredstring (date-time)

Date when the preauthorization was updated

configurationobject

Smart transfer preauthorization configuration

totalAllowedAmountnumber

Maximum amount to be reached by the sum of all transactions that use the consent authorized by the customer.

transactionLimitnumber

Maximum amount for each payment transaction associated with this consent.

periodicLimitsobject

Transactional limits per period as determined by the paying user.

errorDetailobject

Error detail

codestring

Error code

descriptionstring

Error description

detailstring

Error detail

Example response

json

{
  "id": "string",
  "status": "COMPLETED",
  "consentUrl": "string",
  "clientPreauthorizationId": "string",
  "callbackUrls": {},
  "recipients": [
    {
      "type": "BANK_ACCOUNT",
      "id": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
      "name": "Conta empresa",
      "taxNumber": "12345678900",
      "paymentInstitution": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Banco J. Safra S.A.",
        "ispb": "03017677",
        "tradeName": "Banco Safra",
        "compe": "074",
        "createdAt": "2020-04-21T15:00:00.000Z",
        "updatedAt": "2020-04-21T15:00:00.000Z"
      },
      "account": {
        "branch": "0001",
        "number": "123456",
        "type": "CHECKING_ACCOUNT"
      },
      "isDefault": false,
      "pixKey": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "connector": {
    "id": 601,
    "name": "Itaú",
    "primaryColor": "EC7000",
    "institutionUrl": "https://www.itau.com.br",
    "country": "BR",
    "type": "PERSONAL_BANK",
    "credentials": [
      {
        "validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
        "validationMessage": "CPF deve ter 11 números.",
        "label": "CPF",
        "name": "cpf",
        "type": "number",
        "placeholder": "",
        "optional": false
      }
    ],
    "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/201.svg",
    "hasMFA": false,
    "oauth": true,
    "health": {
      "status": "ONLINE",
      "stage": null
    },
    "products": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "IDENTITY",
      "CREDIT_CARDS",
      "PAYMENT_DATA",
      "LOANS",
      "INVESTMENTS"
    ],
    "createdAt": "2023-09-01T18:05:09.145Z",
    "isSandbox": false,
    "isOpenFinance": true,
    "updatedAt": "2024-07-16T15:34:08.028Z",
    "supportsPaymentInitiation": true,
    "supportsScheduledPayments": true,
    "supportsSmartTransfers": true,
    "supportsBoletoManagement": true,
    "supportsAutomaticPix": true
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "configuration": {
    "totalAllowedAmount": 0,
    "transactionLimit": 0,
    "periodicLimits": null
  },
  "errorDetail": {
    "code": "string",
    "description": "string",
    "detail": "string"
  }
}

Code Examples

bash

curl -X POST 'https://api.pluggy.ai/smart-transfers/preauthorizations' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{}'

Try It

API Key

Request Body (JSON)