PluggyDocs
POST/payments/requests

Criar

Cria o recurso de solicitação de pagamento

Request Body

required
object

Request with information to create a payment request

amountrequirednumber

Valor solicitado

descriptionstring

Descrição do pagamento

callbackUrlsobject | null
Any of:
option 1object

Redirect urls after the payment was completed or ended in error status

option 2null | null
recipientIdstring (uuid)

Identificador do recebedor de pagamento

customerIdstring (uuid)

Identificador do cliente associado ao pagamento

clientPaymentIdstring

Seu identificador de pagamento

schedulestring | null

Default: null

One of:
option 1object

Schedule attribute to generate a single payment on a specific future date.

option 2object

Schedule attribute to generate daily payments starting from `startDate`.

option 3object

Schedule attribute to generate weekly payments on a specific day of the week.

option 4object

Schedule attribute to generate monthly payments on a specific day of the month.

option 5object

Schedule attribute to generate payments on an explicit list of dates.

isSandboxboolean

Indica se este pedido de pagamento deve ser criado no modo sandbox. Padrão: falso.

Default: false

Example

json
{
  "amount": 100.5,
  "description": "Transferência",
  "isSandbox": false
}

Responses

200Sucesso ao criar solicitação de pagamento
object

Response with information related to a payment request

idrequiredstring

Identificador principal

amountnumber

Valor solicitado. Para pix automático, não será devolvido.

feesnumber | null

Taxas cobradas pela solicitação de pagamento. Isso inclui tanto as taxas da Pluggy quanto quaisquer taxas específicas do cliente. As taxas são calculadas com base no método de pagamento (PIX ou Boleto) e na configuração de preços do cliente. Para contas de sandbox, as taxas são definidas como 0.

descriptionstring

Descrição do pagamento

statusrequiredstring

Lifecycle of a payment request. - `CREATED`: the request was created and is waiting for a payment intent. - `IN_PROGRESS`: a payment intent is being processed by the institution. - `WAITING_PAYER_AUTHORIZATION`: the payer must authorize the payment at the institution. - `AUTHORIZED`: only for Automatic PIX. The recurring consent was authorized; individual payments will be executed under it. - `SCHEDULED`: the payment is scheduled for a future date. - `COMPLETED`: the payment was confirmed by the institution. - `ERROR`: the payment failed (see `errorDetail`). - `REFUND_IN_PROGRESS`: a refund was requested and is being processed. - `REFUNDED`: the refund was completed. - `REFUND_ERROR`: the refund failed. - `EXPIRED`: the request expired without being paid. - `CANCELED`: the request was canceled.

CREATEDIN_PROGRESSWAITING_PAYER_AUTHORIZATIONAUTHORIZEDSCHEDULEDCOMPLETEDERRORREFUND_IN_PROGRESSREFUNDEDREFUND_ERROREXPIREDCANCELED
clientPaymentIdstring | null

Identificador de pagamento do cliente

createdAtrequiredstring (date-time)

Data em que a solicitação de pagamento foi criada

updatedAtrequiredstring (date-time)

Data em que o pedido de pagamento foi atualizado

callbackUrlsobject | null
Any of:
option 1object

Redirect urls after the payment was completed or ended in error status

option 2null | null
recipientobject | null

Destinatário do pagamento. A forma depende do `tipo` do destinatário.

Any of:
option 1object

Recipient embedded inside a payment request. Polymorphic depending on the kind of payment. - `BANK_ACCOUNT`: a registered bank-account recipient (see `PaymentRecipient`). - `PIX_QR_CODE`: recipient derived from a PIX QR code attached to the request. - `BOLETO`: recipient derived from a boleto attached to the request.

option 2null | null
customerobject | null

Cliente associado à solicitação de pagamento

Any of:
option 1object

Response with information related to a payment customer

option 2null | null
smartAccountobject | null

Conta inteligente que recebe os fundos, quando aplicável

Any of:
option 1object

Pluggy Smart Account (escrow account) attached to a payment request. Receives funds and lets the client orchestrate splits and withdrawals.

option 2null | null
paymentUrlrequiredstring

URL para iniciar o fluxo de criação de intenção de pagamento para esta solicitação de pagamento

pixQrCodestring | null

Código QR Pix gerado pelo recebedor do pagamento

boletoobject | null
Any of:
option 1object

Boleto data

option 2null | null
automaticPixobject

Automatic PIX data

fixedAmountnumber

Valor fixo da cobrança; se preenchido, representa consentimento para pagamentos de valores fixos, não sujeitos a alteração durante a validade do consentimento. Se enviado, minimumVariableAmount e maximumVariableAmount não podem ser fornecidos.

minimumVariableAmountnumber

Valor mínimo permitido por cobrança; se preenchido, representa consentimento para pagamentos de valores variáveis. Se enviado, fixedAmount não pode ser fornecido.

maximumVariableAmountnumber

Valor máximo permitido por cobrança; se preenchido, representa consentimento para pagamentos de valores variáveis. Se enviado, fixedAmount não pode ser fornecido.

startDaterequiredstring (date-time)

Representa a data esperada para a primeira ocorrência de um pagamento associado à recorrência.

expiresAtstring (date-time)

Data de expiração para a autorização automática de pix

isRetryAcceptedboolean

Indica se o cliente receptor tem permissão para fazer tentativas de pagamento, de acordo com as regras estabelecidas no arranjo do Pix.

firstPaymentobject

Definitions for the first payment. It is considered as the user's enrollment payment for the service.

intervalrequiredstring

Permitted frequency for recurring PIX payments under a consent.

WEEKLYMONTHLYQUARTERLYSEMESTERYEARLY
automaticRetriesConfigurationobject

“Configuration for automatic retries. If provided, the scheduled payments associated with this consent will only be retried on the days specified in the array after the original payment date. This does not apply to the first payment, only for scheduled payments.

schedulerConfigurationobject

Configuration for automatic scheduling of payments. When enabled, the system will schedule payments according to the consent interval and start date.

scheduleobject
One of:
option 1object

Schedule attribute to generate a single payment on a specific future date.

option 2object

Schedule attribute to generate daily payments starting from `startDate`.

option 3object

Schedule attribute to generate weekly payments on a specific day of the week.

option 4object

Schedule attribute to generate monthly payments on a specific day of the month.

option 5object

Schedule attribute to generate payments on an explicit list of dates.

option 6null | null
errorDetailobject | null

Detalhes do erro quando a solicitação de pagamento falha

codestring

Error code

providerMessagestring

Error message returned by the institution

isSandboxboolean

Indica se esta solicitação de pagamento está no modo sandbox. Padrão: falso.

Default: false

Example response

json
{
  "id": "c2a6b7d9-3349-435d-8341-44021449ebbc",
  "amount": 150.5,
  "fees": 0.45,
  "description": "Order #4821",
  "status": "CREATED",
  "clientPaymentId": "order-4821",
  "createdAt": "2025-03-12T13:03:45.689Z",
  "updatedAt": "2025-03-12T13:03:45.689Z",
  "callbackUrls": {
    "success": "https://merchant.example.com/orders/4821/success",
    "error": "https://merchant.example.com/orders/4821/error"
  },
  "paymentUrl": "https://pay.pluggy.ai/c2a6b7d9-3349-435d-8341-44021449ebbc",
  "recipient": {
    "type": "BANK_ACCOUNT",
    "id": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
    "name": "Conta empresa",
    "taxNumber": "12345678900",
    "isDefault": true,
    "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"
    },
    "pixKey": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "customer": null,
  "smartAccount": null,
  "pixQrCode": null,
  "boleto": null,
  "automaticPix": null,
  "schedule": null,
  "errorDetail": null,
  "isSandbox": false
}
curl -X POST \
  'https://api.pluggy.ai/payments/requests' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{}'
Resposta de exemplo
{
  "id": "c2a6b7d9-3349-435d-8341-44021449ebbc",
  "amount": 150.5,
  "fees": 0.45,
  "description": "Order #4821",
  "status": "CREATED",
  "clientPaymentId": "order-4821",
  "createdAt": "2025-03-12T13:03:45.689Z",
  "updatedAt": "2025-03-12T13:03:45.689Z",
  "callbackUrls": {
    "success": "https://merchant.example.com/orders/4821/success",
    "error": "https://merchant.example.com/orders/4821/error"
  },
  "paymentUrl": "https://pay.pluggy.ai/c2a6b7d9-3349-435d-8341-44021449ebbc",
  "recipient": {
    "type": "BANK_ACCOUNT",
    "id": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
    "name": "Conta empresa",
    "taxNumber": "12345678900",
    "isDefault": true,
    "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"
    },
    "pixKey": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "customer": null,
  "smartAccount": null,
  "pixQrCode": null,
  "boleto": null,
  "automaticPix": null,
  "schedule": null,
  "errorDetail": null,
  "isSandbox": false
}