Pular para o conteúdo

Create automatic payment request

Starts an automatic (Pix Automático) payment request on the initiation portal. The response returns redirectUrl and paymentRequestId. Send the payer to redirectUrl, then poll Get automatic payment request with the returned id.

POST/api/v1/automatic-payments

Create automatic payment request

Creates an automatic payment request and returns redirectUrl and paymentRequestId for the hosted portal.

Auth: Bearer Token

Request body

4 campos
redirectUri●
bodystring

Allow-listed HTTPS URI where the portal returns after completion.

canBeAutomaticallyRevoked
bodyboolean

Whether the consent may be auto-revoked when business rules allow.

requestExpiresAt
bodystring · date-time

Defines the payment request lifespan: the date and time until which it stays valid, in UTC (`YYYY-MM-DDTHH:mm:ssZ`). Must be in the future. See Request expiration below.

recurringConsent●
bodyobject

Recurring consent payload (logged user, creditors, debtor account, configuration).

loggedUser●
bodyobject

Payer identity captured by the initiator.

document●
bodyobject
identification●
bodystring

CPF or CNPJ without punctuation.

rel●
bodystring

Document type, e.g. CPF or CNPJ.

creditors●
bodyarray<object>

Receiving parties.

personType●
bodystring
cpfCnpj●
bodystring
name●
bodystring
expirationDateTime●
bodystring · date-time

Consent expiry in RFC-3339 UTC.

additionalInformation●
bodystring

Free text entered by the payer in the consent journey.

debtorAccount●
bodyobject

Known debtor account hints (optional parts may still be collected at the holder).

ispb●
bodystring
issuer●
bodystring
number●
bodystring
accountType●
bodystring

CACC | SVGS | TRAN.

recurringConfiguration●
bodyobject

Use either `automatic` or `sweeping` (mutually exclusive product types).

automatic
bodyobject

Pix Automático configuration.

contractId●
bodystring
fixedAmount●
bodystring

Decimal string as per arrangement.

maximumVariableAmount●
bodystring
interval●
bodystring

Frequency code from the arrangement (for example SEMANAL or MONTHLY).

minimumVariableAmount●
bodystring
isRetryAccepted●
bodyboolean
referenceStartDate●
bodystring · date-time
useOverdraftLimit●
bodyboolean
contractDebtor●
bodyobject
name●
bodystring
firstPayment
bodyobject

Optional first subscription payment block.

type●
bodystring
date●
bodystring
currency●
bodystring
amount●
bodystring
remittanceInformation●
bodystring
creditorAccount●
bodyobject
ispb●
bodystring
issuer●
bodystring
number●
bodystring
accountType●
bodystring
cnpjInitiator●
bodystring
paymentConfig●
bodyobject

Recurring settlement settings — populate per your product agreement.

note
bodystring

Opaque keys may be required by your arrangement; see OpenAPI `paymentConfig`.

curl --request POST \
  --url 'https://embedded-payment-manager.hml.linaob.com.br/api/v1/automatic-payments' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SEU_TOKEN>' \
  --data '{
  "redirectUri": "https://your-app.example.com/automatic-pix/return",
  "canBeAutomaticallyRevoked": true,
  "requestExpiresAt": "2025-12-19T18:00:00Z",
  "recurringConsent": {
    "loggedUser": {
      "document": {
        "identification": "76109277673",
        "rel": "CPF"
      }
    },
    "creditors": [
      {
        "personType": "PESSOA_JURIDICA",
        "cpfCnpj": "12345678000195",
        "name": "Merchant Legal Name LTDA"
      }
    ],
    "expirationDateTime": "2025-12-25T08:30:00Z",
    "additionalInformation": "Monthly utility bill",
    "debtorAccount": {
      "ispb": "12345678",
      "issuer": "1774",
      "number": "1234567890",
      "accountType": "CACC"
    },
    "recurringConfiguration": {
      "automatic": {
        "contractId": "XE00038166201907261559y6j6",
        "fixedAmount": "100.00",
        "maximumVariableAmount": "500.00",
        "interval": "MONTHLY",
        "minimumVariableAmount": "10.00",
        "isRetryAccepted": false,
        "referenceStartDate": "2023-05-21T08:30:00Z",
        "useOverdraftLimit": false,
        "contractDebtor": {
          "name": "Payer Full Name"
        },
        "firstPayment": {
          "type": "Pix",
          "date": "2025-01-01",
          "currency": "BRL",
          "amount": "100.12",
          "remittanceInformation": "First charge",
          "creditorAccount": {
            "ispb": "12345678",
            "issuer": "0001",
            "number": "987654",
            "accountType": "CACC"
          },
          "cnpjInitiator": "12345678000195"
        },
        "paymentConfig": {
          "note": "default-plan"
        }
      }
    }
  }
}'

Response

201Automatic payment request created.
Response body
object
  • dataobjectrequired
    • redirectUrlstringrequired

      Hosted portal URL.

    • paymentRequestIdstringrequired

      Identifier for GET /automatic-payments/request/{id}.

  • messagestring
  • typestring
201 · Automatic payment request created.
{
  "data": {
    "redirectUrl": "https://embedded-payment-manager.hml.linaob.com.br/automatic-payments?paymentLinkId=550e8400-e29b-41d4-a716-446655440000",
    "paymentRequestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "",
  "type": "success"
}

Request expiration

requestExpiresAt is optional and limits how long the payer has to authorise. Without it, the request does not expire.

  • It must be a future date and time, in UTC; otherwise the request is rejected with 400.
  • If the payer has not started the authorization by then, the request is closed with status REJEITADO and rejectionReason TEMPO_EXPIRADO_AUTORIZACAO.
  • Once the payer starts the authorization, the deadline becomes 1 hour from that moment, as set by the Open Finance rules.
  • Once the consent is authorised, requestExpiresAt no longer applies.

Next steps