PluggyDocs
POST/payments/requests/{id}/automatic-pix/schedule

Schedule Automatic PIX payment

Schedules an Automatic PIX payment

Parameters

Path Parameters

NameType
idrequired
string (uuid)

Request Body

required
object

Request to schedule an Automatic PIX payment

amountrequirednumber

Transaction value

descriptionstring

Transaction description

daterequiredstring (date)

The payment date, which must fall between D+2 and D+10. Date format must be YYYY-MM-DD (for example: 2025-06-16)

clientPaymentIdstring

External identifier for the payment

recipientIdstring (uuid)

Payment recipient identifier. It should be sent if you want to use a different recipient from the one consented in the payment request (it must have the same tax number as the consented recipient).

Example

json
{
  "amount": 0,
  "description": "string",
  "date": "2024-01-01",
  "clientPaymentId": "string",
  "recipientId": "550e8400-e29b-41d4-a716-446655440000"
}

Responses

200Schedule a Automatic PIX payment.
object

Automatic PIX payment

idrequiredstring

Payment primary identifier

statusrequiredstring

Status of an individual recurring PIX payment. - `SCHEDULED`: the payment has been scheduled at the institution. - `CREATED`: the payment is created and pending execution. - `COMPLETED`: the payment was confirmed. - `CANCELED`: the payment was canceled. - `ERROR`: the payment failed (see `errorDetail`).

SCHEDULEDCREATEDCOMPLETEDCANCELEDERROR
amountrequirednumber

Payment amount

descriptionstring

Payment description

daterequiredstring (date)

Payment scheduled date

endToEndIdstring

Payment end to end identifier

errorDetailobject

Details about an error that occurred with the automatic PIX payment

coderequiredstring

Error codes expected during payment processing: - SALDO_INSUFICIENTE: The selected account does not have sufficient balance to make the payment. - VALOR_ACIMA_LIMITE: Validates if the amount exceeds the limit established [by the institution (account or channel)/in the arrangement] to allow the client to perform transactions. - VALOR_INVALIDO: The submitted amount is not valid. - NAO_INFORMADO: Not reported/identified by the account-holding institution. - PAGAMENTO_DIVERGENTE_CONSENTIMENTO: Payment data differs from consent data. - PAGAMENTO_RECUSADO_DETENTORA: [description of the reason for refusal]. - PAGAMENTO_RECUSADO_SPI: [error code according to PACS.002 reason domain table]. - CONSENTIMENTO_INVALIDO: Invalid consent (in final status). - FALHA_INFRAESTRUTURA_SPI: Indicates a failure in the Instant Payments System (SPI). - FALHA_INFRAESTRUTURA_ICP: Indicates a failure in the Public Key Infrastructure (ICP). - FALHA_INFRAESTRUTURA_PSP_RECEBEDOR: Indicates a failure in the infrastructure of the Payment Service Provider (PSP) that receives the payment. - FALHA_INFRAESTRUTURA_DETENTORA: Indicates a failure in the infrastructure of the institution holding the information or resources. - TITULARIDADE_INCONSISTENTE: Account currently not associated with the CPF/CNPJ of the long-term consent. - LIMITE_PERIODO_VALOR_EXCEDIDO: The transaction cannot be performed because the amount parameterized in the consent has been exceeded. - LIMITE_PERIODO_QUANTIDADE_EXCEDIDO: The transaction cannot be performed because the quantity parameterized in the consent has been exceeded. - LIMITE_VALOR_TOTAL_CONSENTIMENTO_EXCEDIDO: The transaction amount exceeds the global consent limit. - LIMITE_VALOR_TRANSACAO_CONSENTIMENTO_EXCEDIDO: The transaction amount exceeds the per-transaction limit set in the consent. - LIMITE_TENTATIVAS_EXCEDIDO: The maximum number of settlement attempts allowed by the arrangement has been reached. - CONSENTIMENTO_REVOGADO: The payment was associated with a consent that has been revoked. - FORA_PRAZO_PERMITIDO: The request time or period does not allow scheduling by the holder. - DETALHE_TENTATIVA_INVALIDO: The parameter(s) [field_name(s)] entered for the new payment attempt do not match the original failed payment and are not allowed in the new attempt. - DETALHE_PAGAMENTO_INVALIDO: Validates if a given parameter provided complies with the business rules.

SALDO_INSUFICIENTEVALOR_ACIMA_LIMITEVALOR_INVALIDONAO_INFORMADOPAGAMENTO_DIVERGENTE_CONSENTIMENTOPAGAMENTO_RECUSADO_DETENTORAPAGAMENTO_RECUSADO_SPICONSENTIMENTO_INVALIDOFALHA_INFRAESTRUTURA_SPIFALHA_INFRAESTRUTURA_ICPFALHA_INFRAESTRUTURA_PSP_RECEBEDORFALHA_INFRAESTRUTURA_DETENTORATITULARIDADE_INCONSISTENTELIMITE_PERIODO_VALOR_EXCEDIDOLIMITE_PERIODO_QUANTIDADE_EXCEDIDOLIMITE_VALOR_TOTAL_CONSENTIMENTO_EXCEDIDOLIMITE_VALOR_TRANSACAO_CONSENTIMENTO_EXCEDIDOLIMITE_TENTATIVAS_EXCEDIDOCONSENTIMENTO_REVOGADOFORA_PRAZO_PERMITIDODETALHE_TENTATIVA_INVALIDODETALHE_PAGAMENTO_INVALIDO
detailrequiredstring

Additional details about the error

clientPaymentIdstring

External identifier for the payment

recipientIdrequiredstring (uuid)

Payment recipient identifier

isFirstPaymentboolean

Indicates if this is the first payment

attemptsobject[]
itemsobject

Payment attempt. It represents an attempt to complete this payment. Useful for tracking the payment history.

Example response

json
{
  "id": "string",
  "status": "SCHEDULED",
  "amount": 0,
  "description": "string",
  "date": "2024-01-01",
  "endToEndId": "string",
  "errorDetail": {
    "code": "SALDO_INSUFICIENTE",
    "detail": "string"
  },
  "clientPaymentId": "string",
  "recipientId": "550e8400-e29b-41d4-a716-446655440000",
  "isFirstPayment": true,
  "attempts": [
    {
      "id": "string",
      "status": "IN_PROGRESS",
      "endToEndId": "string",
      "date": "2024-01-01",
      "errorDetail": {
        "code": "SALDO_INSUFICIENTE",
        "detail": "string"
      }
    }
  ]
}

Code Examples

bash
curl -X POST 'https://api.pluggy.ai/payments/requests/{id}/automatic-pix/schedule' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{}'

Try It

Path Parameters