Pular para o conteúdo

Create recurring consent

Creates an automatic-payment contract (recurring consent) for Smart Pix / Sweeping. Send either an existing id or a full recurringConsent object so the platform creates a payment request for you.

On 201 Created, persist data.id (poll Get payment request), data.consentId (use as recurringConsentId when calling Create recurring payment), and redirect the user to data.redirectUrl.

The recurringConsent.redirectUri you send is where the account holder returns the browser after consent — it must be allow-listed for your sub-tenant.

POST/api/v1/automatic-payments/recurring-consents

Create recurring consent

Creates a recurring consent for automatic payments and returns redirectUrl, id, and consentId.

Auth: Bearer Token

Cabeçalhos

1 campo
subTenantId●
headerstring

Subtenant under which the consent is created.

Corpo da requisição

4 campos
organisationId●
bodystring

Organisation id from Get registered participants.

authorisationServerId●
bodystring

Authorisation server id from Get registered participants.

id
bodystring

Optional existing automatic payment request id when you are not sending recurringConsent.

recurringConsent
bodyobject

Consent payload when the API must create a payment request for you. Omit when `id` is sent to reuse an existing payment request.

loggedUser●
bodyobject

Logged payer identity at the initiator.

document●
bodyobject
identification●
bodystring

CPF or CNPJ (digits only).

rel●
bodystring

Document type (for example `CPF`, `CNPJ`).

businessEntity
bodyobject

Required when the logged user is a legal entity (`CNPJ`).

document●
bodyobject
identification●
bodystring
rel●
bodystring
redirectUri
bodystring

Your HTTPS callback after the holder completes consent (allow-listed domain).

creditors●
bodyarray<[object Object]>

Receiving parties for the recurring arrangement.

expirationDateTime●
bodystring · date-time

Consent expiry (RFC 3339, UTC).

additionalInformation●
bodystring

Free-text note shown in consent when applicable.

debtorAccount●
bodyobject

Debtor account known at initiation (optional at holder).

ispb●
bodystring
issuer●
bodystring
number●
bodystring
accountType●
bodystring
recurringConfiguration●
bodyobject

`oneOf` wrapper: send **`sweeping`** (Sweeping schema) or **`automatic`** (Automatic schema) — not both.

sweeping
bodyobject

Payload matching `#/components/schemas/Sweeping`. Required when using Smart Pix / Sweeping.

totalAllowedAmount●
bodystring

Maximum cumulative amount for all transactions under this consent (sum cap).

transactionLimit●
bodystring

Maximum amount per individual payment transaction.

periodicLimits
bodyobject

Optional transactional limits by calendar period. Include the period keys your arrangement requires (`day`, `week`, `month`, or `year`) — each value is an object with `quantityLimit` and `transactionLimit` (strings, decimal format).

day
bodyobject

Daily bucket limits.

quantityLimit
bodystring

Maximum number of transactions in the period.

transactionLimit
bodystring

Maximum total amount in the period.

week
bodyobject

Weekly bucket limits.

quantityLimit
bodystring
transactionLimit
bodystring
month
bodyobject

Monthly bucket limits.

quantityLimit
bodystring
transactionLimit
bodystring
year
bodyobject

Yearly bucket limits.

quantityLimit
bodystring
transactionLimit
bodystring
startDateTime●
bodystring · date-time

When the consent becomes valid (RFC 3339, UTC). If omitted by rule, the holder may align it with creation time — see OpenAPI.

curl --request POST \
  --url 'https://embedded-payment-manager.hml.linaob.com.br/api/v1/automatic-payments/recurring-consents' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SEU_TOKEN>' \
  --header 'subTenantId: subtenant_abc123' \
  --data '{
  "organisationId": "c8f0bf49-4744-4933-8960-7add6e590841",
  "authorisationServerId": "c8f0bf49-4744-4933-8960-7add6e590841",
  "id": "f3b4e8c2-2c1d-4f6a-9c1e-5a92f3a7d8a1",
  "recurringConsent": {
    "loggedUser": {
      "document": {
        "identification": "76109277673",
        "rel": "CPF"
      }
    },
    "businessEntity": {
      "document": {
        "identification": "12345678000195",
        "rel": "CNPJ"
      }
    },
    "redirectUri": "https://your-app.example.com/smart-pix/callback",
    "expirationDateTime": "2027-12-25T08:30:00Z",
    "additionalInformation": "Sweeping contract — operational account",
    "debtorAccount": {
      "ispb": "12345678",
      "issuer": "0001",
      "number": "1234567890",
      "accountType": "CACC"
    },
    "recurringConfiguration": {
      "sweeping": {
        "totalAllowedAmount": "100000.00",
        "transactionLimit": "5000.00",
        "periodicLimits": {
          "day": {
            "quantityLimit": "2",
            "transactionLimit": "100000.12"
          },
          "week": {
            "quantityLimit": "2",
            "transactionLimit": "100000.12"
          },
          "month": {
            "quantityLimit": "2",
            "transactionLimit": "100000.12"
          },
          "year": {
            "quantityLimit": "2",
            "transactionLimit": "100000.12"
          }
        },
        "startDateTime": "2026-05-01T08:30:00Z"
      }
    }
  }
}'

Response

201Recurring consent created successfully.
Response body
object
  • dataobjectrequired
    • idstringrequired

      Automatic payment request id — use as `{automaticPaymentsRequestId}` on GET payment request.

    • consentIdstringrequired

      Consent identifier — use as `recurringConsentId` on create recurring payment.

    • redirectUrlstringrequired

      URL where the payer completes authentication at the account holder.

  • messagestring

    Response message.

  • typestring

    Envelope type (for example `success`).

201 · Recurring consent created successfully.
{
  "data": {
    "id": "f3b4e8c2-2c1d-4f6a-9c1e-5a92f3a7d8a1",
    "consentId": "urn:consent:abc123",
    "redirectUrl": "https://holder.example.com/authorize?request=xyz"
  },
  "message": "",
  "type": "success"
}

Next steps