POST/payments/requests

Create

Creates the payment request resource

Request Body

required

object

Request with information to create a payment request

amountrequirednumber

Requested amount

descriptionstring

Payment description

callbackUrlsobject

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

successstring

Url to be redirected after the payment was completed

pendingstring

Url to be redirected when the payment is pending (for example, when it has status WAITING_PAYER_AUTHORIZATION

errorstring

Url to be redirected after the payment ended in error status

recipientIdstring (uuid)

Payment receiver identifier

customerIdstring (uuid)

Customer identifier associated to the payment

clientPaymentIdstring

Your payment identifier

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

Indicates if this payment request should be created in sandbox mode. Default: false.

Default: false

Example

json

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

Responses

200Success creating payment request

object

Response with information related to a payment request

idrequiredstring

Primary identifier

amountnumber

Requested amount. For automatic pix it won't be returned

feesnumber

Fees charged for the payment request. This includes both Pluggy's fees and any customer-specific fees. Fees are calculated based on the payment method (PIX or Boleto) and the client's pricing configuration. For sandbox accounts, fees are set to 0.

descriptionstring

Payment description

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

Client payment identifier

createdAtrequiredstring (date-time)

Date when the payment request was created

updatedAtrequiredstring (date-time)

Date when the payment request was updated

callbackUrlsobject

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

successstring

Url to be redirected after the payment was completed

pendingstring

Url to be redirected when the payment is pending (for example, when it has status WAITING_PAYER_AUTHORIZATION

errorstring

Url to be redirected after the payment ended in error status

recipientobject | nullnullable

Recipient of the payment. Shape depends on the recipient `type`.

All of:

part 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.

customerobject | nullnullable

Customer associated with the payment request

All of:

part 1object

Response with information related to a payment customer

smartAccountobject | nullnullable

Smart account that receives the funds, when applicable

All of:

part 1object

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

paymentUrlrequiredstring

URL to begin the payment intent creation flow for this payment request

pixQrCodestring

Pix QR code generated by the payment receiver

boletoobject

Boleto data

digitableLinerequiredstring

Boleto digitable line

barcoderequiredstring

Boleto barcode

payerrequiredobject

Boleto payer information

recipientrequiredobject

Boleto recipient information

datestring (date-time)

Boleto issue date

dueDaterequiredstring (date-time)

Boleto due date

expirationDatestring (date-time)

After this date, the boleto cannot be paid

baseAmountrequirednumber

Boleto original amount, without interests, penalties and discounts

penaltyAmountrequirednumber

Boleto penalty amount. If there is no penalty, it will be returned as zero

interestAmountnumber

Boleto interest amount. If there is no interest, it will be returned as zero

discountAmountrequirednumber

Boleto discount amount. If there is no discounts, it will be returned as zero

totalAmountrequirednumber

Boleto final amount. It is equal to the base amount plus penalties and interests, minus discounts

updatedAtstring (date-time)

Date when the lastest information of this boleto has been retrieved

automaticPixobject

Automatic PIX data

fixedAmountnumber

Fixed charge amount; if filled in, it represents consent for payments of fixed amounts, not subject to change during the validity of the consent. If it's sent, minimumVariableAmount and maximumVariableAmount cannot be provided.

minimumVariableAmountnumber

Minimum amount allowed per charge; if filled in, it represents consent for payments of variable amounts. If it's sent, fixedAmount cannot be provided.

maximumVariableAmountnumber

Maximum amount allowed per charge; if filled in, it represents consent for payments of variable amounts. If it's sent, fixedAmount cannot be provided.

startDaterequiredstring (date-time)

Represents the expected date for the first occurrence of a payment associated with the recurrence.

expiresAtstring (date-time)

Expiration date for the automatic pix authorization

isRetryAcceptedboolean

Indicates whether the receiving customer is allowed to make payment attempts, according to the rules established in the Pix arrangement.

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.

errorDetailobject

Error details when payment request fails

codestring

Error code

providerMessagestring

Error message returned by the institution

isSandboxboolean

Indicates if this payment request is in sandbox mode. Default: false.

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
}

Code Examples

bash

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

Try It

API Key

Request Body (JSON)