Create a single Pix Request Schedule

​

Creates a new single Pix payment schedule. For recurring schedules use /pix-schedules/recurrences.

Headers
  • Idempotency-Key
    Type: string
    required
Body·
required
application/json

Request payload for creating a single (one-shot) scheduled outgoing Pix payment. Recurrence-related fields live on /pix-schedules/recurrences.

  • amount
    Type: number
    required

    Transaction amount.

  • initiationMethod
    Type: string enum
    required

    Payment initiation method.

    values
    • APDN
    • APES
    • AUTO
    • DICT
    • INIC
    • MANU
    • QRDN
    • QRES
  • receiver
    Type: object ·
    required

    Receiver/beneficiary information for the Pix transaction

  • scheduledDate
    Type: string Format: date
    required

    Date when this schedule will be executed (yyyy-MM-dd). Must be after the current day on the Brazilian calendar: a same-day schedule is refused with PIX-SCH-0022.

  • sender
    Type: object ·
    required

    Payer/sender information for the Pix transaction

  • description
    Type: string

    Payment description or message to the receiver.

  • endToEndId
    Type: string

    End-to-end identifier.

  • metadata
    Type: array object[] ·

    Optional list of custom key/value pairs.

    Key/value metadata item

  • priority
    Type: string enum

    Payment priority for the outgoing Pix request (SPI band: HIGH → HIGH, NORM → NORM)

    values
    • HIGH
    • NORM
  • purpose
    Type: string enum

    Purpose of the outgoing Pix payment (SPI purpose codes)

    values
    • GSCB
    • IPAY
    • IPRT
    • OTHR
    • REFU
  • reconciliationId
    Type: string

    Client reconciliation identifier for reporting and matching. Alphanumeric only ([a-zA-Z0-9]); the length depends on initiationMethod: up to 25 for QRES, APES and INIC, and 26 to 35 for QRDN, APDN and AUTO.

  • source
    Type: string enum

    Origin. Defaults to MANUAL.

    values
    • MANUAL
    • PIX_AUTOMATIC
Responses
  • application/json
  • 400

    Invalid request

    Erros desta resposta

    Código interno HTTP Descrição Erro normativo Bacen
    PIX-SCH-0005 400 Invalid schedule start date —
    PIX-SCH-0011 400 mandateId is required when source is PIX_AUTOMATIC —
    PIX-SCH-0012 400 preassignedEndToEndId is required when source is PIX_AUTOMATIC —
    PIX-SCH-0014 400 initiationMethod must be AUTO when source is PIX_AUTOMATIC —
    PIX-SCH-0017 400 initiationMethod is required —
Request Example for post/api/v1/pix-schedules
curl http://localhost/api/v1/pix-schedules \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "initiationMethod": "DICT",
  "amount": 123.98,
  "sender": {
    "name": "Joao da Silva",
    "document": {
      "type": "CPF",
      "value": "12345678901"
    },
    "account": {
      "ispb": "12345678",
      "type": "CACC",
      "branch": "0001",
      "number": "12345678"
    }
  },
  "receiver": {
    "key": "+5511989450870",
    "name": "Joao da Silva",
    "document": {
      "type": "CPF",
      "value": "12345678901"
    },
    "account": {
      "ispb": "12345678",
      "type": "CACC",
      "branch": "0001",
      "number": "12345678"
    }
  },
  "description": "",
  "reconciliationId": "REC20260408001",
  "priority": "HIGH",
  "metadata": [
    {
      "key": "orderId",
      "value": "ORD-1001"
    }
  ],
  "purpose": "IPAY",
  "source": "MANUAL",
  "endToEndId": "E1234567820260316143000ABC12345",
  "scheduledDate": "2026-04-30"
}'

{
  "id": "c0a8012e-1234-5678-90ab-000000000001",
  "status": "ACTIVE",
  "createdAt": "2026-03-01T09:30:00",
  "updatedAt": "2026-03-15T12:00:00",
  "initiationMethod": "MANU",
  "priority": "NORM",
  "priorityType": "PAGAGD",
  "purpose": "IPAY",
  "amount": 150,
  "userDescription": "Gym membership",
  "sender": {
    "name": "Joao da Silva",
    "document": {
      "type": "CPF",
      "value": "12345678901"
    },
    "account": {
      "ispb": "12345678",
      "type": "CACC",
      "branch": "0001",
      "number": "12345678"
    }
  },
  "receiver": {
    "key": "+5511989450870",
    "name": "Joao da Silva",
    "document": {
      "type": "CPF",
      "value": "12345678901"
    },
    "account": {
      "ispb": "12345678",
      "type": "CACC",
      "branch": "0001",
      "number": "12345678"
    }
  },
  "source": "MANUAL",
  "scheduledDate": "2026-04-30",
  "endToEndId": "E1234567820260430143000ABC12345",
  "msgId": "M20260101000000001",
  "settledAt": "2026-06-22T14:30:00Z",
  "failureReason": "FF08",
  "recurrenceId": "c0a8012e-1234-5678-90ab-000000000002",
  "installment": 3,
  "totalInstallments": 12,
  "reconciliationId": "REC20260408001",
  "totalAmount": 150
}

Schedule created and accepted