Skip to main content
POST
/
v1
/
schedules
Create a Pix Schedule
curl --request POST \
  --url https://plugin-pix-indirect.api.lerian.net/v1/schedules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "100.50",
  "initiationId": "550e8400-e29b-41d4-a716-446655440010",
  "scheduledFor": "2026-08-15T00:00:00Z",
  "description": "Recurring charge installment 03/12",
  "endToEndId": "E1234567820260815060012345678901",
  "maxAttempts": 2,
  "recurrenceId": "01988a7c-1234-7abc-8def-111122223333"
}
'
import requests

url = "https://plugin-pix-indirect.api.lerian.net/v1/schedules"

payload = {
    "amount": "100.50",
    "initiationId": "550e8400-e29b-41d4-a716-446655440010",
    "scheduledFor": "2026-08-15T00:00:00Z",
    "description": "Recurring charge installment 03/12",
    "endToEndId": "E1234567820260815060012345678901",
    "maxAttempts": 2,
    "recurrenceId": "01988a7c-1234-7abc-8def-111122223333"
}
headers = {
    "X-Account-Id": "<x-account-id>",
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    'X-Account-Id': '<x-account-id>',
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '100.50',
    initiationId: '550e8400-e29b-41d4-a716-446655440010',
    scheduledFor: '2026-08-15T00:00:00Z',
    description: 'Recurring charge installment 03/12',
    endToEndId: 'E1234567820260815060012345678901',
    maxAttempts: 2,
    recurrenceId: '01988a7c-1234-7abc-8def-111122223333'
  })
};

fetch('https://plugin-pix-indirect.api.lerian.net/v1/schedules', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://plugin-pix-indirect.api.lerian.net/v1/schedules",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '100.50',
    'initiationId' => '550e8400-e29b-41d4-a716-446655440010',
    'scheduledFor' => '2026-08-15T00:00:00Z',
    'description' => 'Recurring charge installment 03/12',
    'endToEndId' => 'E1234567820260815060012345678901',
    'maxAttempts' => 2,
    'recurrenceId' => '01988a7c-1234-7abc-8def-111122223333'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Account-Id: <x-account-id>",
    "X-Idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://plugin-pix-indirect.api.lerian.net/v1/schedules"

	payload := strings.NewReader("{\n  \"amount\": \"100.50\",\n  \"initiationId\": \"550e8400-e29b-41d4-a716-446655440010\",\n  \"scheduledFor\": \"2026-08-15T00:00:00Z\",\n  \"description\": \"Recurring charge installment 03/12\",\n  \"endToEndId\": \"E1234567820260815060012345678901\",\n  \"maxAttempts\": 2,\n  \"recurrenceId\": \"01988a7c-1234-7abc-8def-111122223333\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://plugin-pix-indirect.api.lerian.net/v1/schedules")
  .header("X-Account-Id", "<x-account-id>")
  .header("X-Idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"100.50\",\n  \"initiationId\": \"550e8400-e29b-41d4-a716-446655440010\",\n  \"scheduledFor\": \"2026-08-15T00:00:00Z\",\n  \"description\": \"Recurring charge installment 03/12\",\n  \"endToEndId\": \"E1234567820260815060012345678901\",\n  \"maxAttempts\": 2,\n  \"recurrenceId\": \"01988a7c-1234-7abc-8def-111122223333\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://plugin-pix-indirect.api.lerian.net/v1/schedules")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Account-Id"] = '<x-account-id>'
request["X-Idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"100.50\",\n  \"initiationId\": \"550e8400-e29b-41d4-a716-446655440010\",\n  \"scheduledFor\": \"2026-08-15T00:00:00Z\",\n  \"description\": \"Recurring charge installment 03/12\",\n  \"endToEndId\": \"E1234567820260815060012345678901\",\n  \"maxAttempts\": 2,\n  \"recurrenceId\": \"01988a7c-1234-7abc-8def-111122223333\"\n}"

response = http.request(request)
puts response.read_body
{
  "accountId": "019cf6ef-e418-7ced-80c0-7b9816faa798",
  "amount": "100.50",
  "attemptCount": 0,
  "attempts": [
    {
      "attemptedAt": "2026-08-15T06:00:02Z",
      "endToEndId": "E1234567820260815060011111111111",
      "failureMessage": "Midaz error: balance below required (06:00 BRT attempt)",
      "failureReason": "INSUFFICIENT_FUNDS",
      "initiationId": "a1111111-1111-4111-8111-111111111111",
      "transferId": "f1a2b3c4-1111-4d5e-9f6a-7b8c9d0e1f23"
    }
  ],
  "cancelledAt": "2026-05-19T09:15:33Z",
  "createdAt": "2026-05-26T12:30:00Z",
  "description": "Recurring charge installment 03/12",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "123456789",
      "participant": "12345678",
      "type": "CACC"
    },
    "key": "john.doe@example.com",
    "owner": {
      "document": "12345678901",
      "name": "John Doe",
      "tradeName": "John's Business"
    }
  },
  "endToEndId": "E1234567820260815060012345678901",
  "executedAt": "2026-08-15T06:00:04Z",
  "failedAt": "2026-08-15T06:00:04Z",
  "failureMessage": "<string>",
  "failureReason": "INSUFFICIENT_FUNDS",
  "firedAt": "2026-08-15T06:00:04Z",
  "id": "01989f9e-6508-79f8-9540-835be49fbd0d",
  "initiationId": "550e8400-e29b-41d4-a716-446655440010",
  "initiationType": "MANUAL",
  "maxAttempts": 2,
  "recurrenceId": "01988a7c-1234-7abc-8def-111122223333",
  "scheduledFor": "2026-08-15T09:00:00Z",
  "status": "SCHEDULED",
  "transferId": "c8d27e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "updatedAt": "2026-05-26T12:30:00Z"
}
{
  "code": "<string>",
  "title": "<string>",
  "message": "<string>"
}
{
  "code": "<string>",
  "title": "<string>",
  "message": "<string>"
}
{
  "code": "<string>",
  "title": "<string>",
  "message": "<string>"
}
{
  "code": "<string>",
  "title": "<string>",
  "message": "<string>"
}
{
  "code": "<string>",
  "title": "<string>",
  "message": "<string>"
}
{
  "code": "<string>",
  "title": "<string>",
  "message": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Account-Id
string
required

Unique identifier of the Midaz Ledger Account (UUID format).

​
X-Idempotency
string
required

Idempotency key (UUID v4 recommended); replays return the cached 201 response.

Body

application/json
​
amount
string
required

Amount is the transfer amount in BRL with 2 decimal places (e.g. "100.50"). Format and bounds are validated when the schedule fires.

Example:

"100.50"

​
initiationId
string
required

InitiationID anchors the schedule to an existing payment initiation that already carries the DICT-validated destination snapshot. The schedule copies that initiation's destination fields and stores the reference as an audit anchor (never reused at fire time). An initiation must exist before creating the schedule.

Example:

"550e8400-e29b-41d4-a716-446655440010"

​
scheduledFor
string<date-time>
required

ScheduledFor is the wall-clock fire date in ISO 8601 with timezone. The actual execution moment is resolved from this value plus the service default execution hour (BRT). Recurring callers must set this to >= D-1 of the due date.

Example:

"2026-08-15T00:00:00Z"

​
description
string

Description is the optional human-readable transfer message: optional, max 140 characters; HTML or script content is rejected. Optional at the Pix / BACEN level (informacoesEntreUsuarios).

Maximum string length: 140
Example:

"Recurring charge installment 03/12"

​
endToEndId
string

EndToEndID is the optional caller-minted BACEN end-to-end identifier for the scheduled Pix. It is not header-bound and not required, so generic HTTP callers omit it. Recurring (Pix Automático) callers that mint the cashout end-to-end id up front supply it so the scheduled fire reuses the same identifier. Its format is validated when the payment is processed.

Example:

"E1234567820260815060012345678901"

​
maxAttempts
integer

MaxAttempts caps the number of fire attempts allowed for this schedule. Pix Automático payer uses 2 (first attempt at 06:00 BRT, INSUFFICIENT_FUNDS retry at 18:00 BRT). Zero or omitted falls back to the service default.

Required range: 1 <= x <= 2
Example:

2

​
recurrenceId
string

RecurrenceID is a generic correlation anchor that groups multiple schedules created by the same upstream flow (recurring payment, subscription, installment plan, billing cycle, etc.). Optional. The schedule layer does NOT interpret this value — it is opaque metadata echoed back on GET / LIST and on the schedule.* outbound webhooks so the upstream consumer can re-aggregate. Nil for ad-hoc one-off schedules that have no parent group.

Example:

"01988a7c-1234-7abc-8def-111122223333"

Response

Created

​
accountId
string

AccountID echoes the input AccountID for audit / log correlation.

Example:

"019cf6ef-e418-7ced-80c0-7b9816faa798"

​
amount
string

Amount is the BRL amount with 2 decimal places.

Example:

"100.50"

​
attemptCount
integer

AttemptCount is the number of fire attempts made so far.

Example:

0

​
attempts
object[]

Attempts is the chronological list of failed prior fire attempts. The successful attempt is not included here; it is recorded on the schedule itself via its TransferID and EndToEndID. Empty array when no failures have been recorded.

​
cancelledAt
string<date-time>

CancelledAt is the moment the schedule reached CANCELLED. Absent for non-CANCELLED rows.

Example:

"2026-05-19T09:15:33Z"

​
createdAt
string<date-time>

CreatedAt is the persistence timestamp (ISO 8601 UTC).

Example:

"2026-05-26T12:30:00Z"

​
description
string

Description is the optional human-readable transfer message.

Example:

"Recurring charge installment 03/12"

​
destination
object

Destination is the destination snapshot captured on the schedule.

​
endToEndId
string

EndToEndID is the BACEN end-to-end identifier of the settled transfer (resolved via TransferID). Absent for non-EXECUTED states.

Example:

"E1234567820260815060012345678901"

​
executedAt
string<date-time>

ExecutedAt is the moment the schedule reached EXECUTED. Absent for non-EXECUTED rows.

Example:

"2026-08-15T06:00:04Z"

​
failedAt
string<date-time>

FailedAt is the moment the schedule reached the terminal FAILED state. Absent for non-FAILED rows. Symmetric with ExecutedAt / CancelledAt.

Example:

"2026-08-15T06:00:04Z"

​
failureMessage
string

FailureMessage is the free-text (PII-sanitized) human-readable failure description. Absent for non-FAILED rows.

​
failureReason
enum<string>

FailureReason categorizes a terminal failure. Snapshot of the latest Attempts[] entry's FailureReason. Absent for non-FAILED rows.

Available options:
INSUFFICIENT_FUNDS,
BTG_REJECTED,
MIDAZ_REJECTED,
VALIDATION_FAILED,
SCHEDULE_STALE_TIMEOUT,
SCHEDULE_RETRIES_EXHAUSTED
Example:

"INSUFFICIENT_FUNDS"

​
firedAt
string<date-time>

FiredAt is the most recent dispatch instant. Absent until the schedule starts processing (PROCESSING / EXECUTED / FAILED).

Example:

"2026-08-15T06:00:04Z"

​
id
string

ID is the unique schedule identifier (UUID v7, app-generated).

Example:

"01989f9e-6508-79f8-9540-835be49fbd0d"

​
initiationId
string

InitiationID is the payment initiation referenced at create time (audit anchor). It is never reused at fire time; each fire attempt uses its own initiation, surfaced per attempt as Attempts[].InitiationID.

Example:

"550e8400-e29b-41d4-a716-446655440010"

​
initiationType
enum<string>

InitiationType records how the destination was captured (MANUAL, KEY, QR_CODE).

Available options:
MANUAL,
KEY,
QR_CODE
Example:

"MANUAL"

​
maxAttempts
integer

MaxAttempts is the per-row retry cap accepted at create time.

Example:

2

​
recurrenceId
string

RecurrenceID echoes the parent recurrence anchor when the schedule was created from a recurring flow. Empty for direct POST /v1/schedules calls.

Example:

"01988a7c-1234-7abc-8def-111122223333"

​
scheduledFor
string<date-time>

ScheduledFor is the wall-clock fire moment (ISO 8601 UTC).

Example:

"2026-08-15T09:00:00Z"

​
status
enum<string>

Status is the schedule lifecycle status. Always SCHEDULED on create. Lifecycle: SCHEDULED -> PROCESSING -> EXECUTED | FAILED | CANCELLED.

Available options:
SCHEDULED,
PROCESSING,
EXECUTED,
FAILED,
CANCELLED
Example:

"SCHEDULED"

​
transferId
string

TransferID is the identifier of the settled transfer. Populated only on EXECUTED.

Example:

"c8d27e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f"

​
updatedAt
string<date-time>

UpdatedAt is the last status-transition timestamp (ISO 8601 UTC).

Example:

"2026-05-26T12:30:00Z"