Request a PIX Automatico authorization

curl --request POST \
  --url https://api.example.com/v1/pix-automatico/authorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractNumber": "1234567890ABC",
  "createdDateTime": "2024-01-05T10:00:00.000Z",
  "expirationDateTime": "2024-01-06T10:00:00.000Z",
  "frequency": 1,
  "payer": {
    "account": "0007654321",
    "cpfCnpj": "04623217035",
    "ispb": "00038166",
    "personType": 0,
    "agency": "0001"
  },
  "recipient": {
    "cnpj": "61695227000193",
    "ispb": "04358798",
    "name": "Enel"
  },
  "recurrenceId": "RR0435879820240605njua7shf40o",
  "solicitationDateTime": "2024-01-05T10:00:00.000Z",
  "startDate": "2024-01-10",
  "amount": 110001,
  "contractDesc": "Conta de energia",
  "endDate": "2026-01-10",
  "floorMaxAmount": 55000
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/pix-automatico/authorizations"

	payload := strings.NewReader("{\n  \"contractNumber\": \"1234567890ABC\",\n  \"createdDateTime\": \"2024-01-05T10:00:00.000Z\",\n  \"expirationDateTime\": \"2024-01-06T10:00:00.000Z\",\n  \"frequency\": 1,\n  \"payer\": {\n    \"account\": \"0007654321\",\n    \"cpfCnpj\": \"04623217035\",\n    \"ispb\": \"00038166\",\n    \"personType\": 0,\n    \"agency\": \"0001\"\n  },\n  \"recipient\": {\n    \"cnpj\": \"61695227000193\",\n    \"ispb\": \"04358798\",\n    \"name\": \"Enel\"\n  },\n  \"recurrenceId\": \"RR0435879820240605njua7shf40o\",\n  \"solicitationDateTime\": \"2024-01-05T10:00:00.000Z\",\n  \"startDate\": \"2024-01-10\",\n  \"amount\": 110001,\n  \"contractDesc\": \"Conta de energia\",\n  \"endDate\": \"2026-01-10\",\n  \"floorMaxAmount\": 55000\n}")

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

	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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contractNumber: '1234567890ABC',
    createdDateTime: '2024-01-05T10:00:00.000Z',
    expirationDateTime: '2024-01-06T10:00:00.000Z',
    frequency: 1,
    payer: {
      account: '0007654321',
      cpfCnpj: '04623217035',
      ispb: '00038166',
      personType: 0,
      agency: '0001'
    },
    recipient: {cnpj: '61695227000193', ispb: '04358798', name: 'Enel'},
    recurrenceId: 'RR0435879820240605njua7shf40o',
    solicitationDateTime: '2024-01-05T10:00:00.000Z',
    startDate: '2024-01-10',
    amount: 110001,
    contractDesc: 'Conta de energia',
    endDate: '2026-01-10',
    floorMaxAmount: 55000
  })
};

fetch('https://api.example.com/v1/pix-automatico/authorizations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/pix-automatico/authorizations"

payload = {
    "contractNumber": "1234567890ABC",
    "createdDateTime": "2024-01-05T10:00:00.000Z",
    "expirationDateTime": "2024-01-06T10:00:00.000Z",
    "frequency": 1,
    "payer": {
        "account": "0007654321",
        "cpfCnpj": "04623217035",
        "ispb": "00038166",
        "personType": 0,
        "agency": "0001"
    },
    "recipient": {
        "cnpj": "61695227000193",
        "ispb": "04358798",
        "name": "Enel"
    },
    "recurrenceId": "RR0435879820240605njua7shf40o",
    "solicitationDateTime": "2024-01-05T10:00:00.000Z",
    "startDate": "2024-01-10",
    "amount": 110001,
    "contractDesc": "Conta de energia",
    "endDate": "2026-01-10",
    "floorMaxAmount": 55000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "idReqJdPi": "52c43361-caa1-4ddb-9152-708426a25db3",
  "recurrenceId": "RR0435879820240605njua7shf40o",
  "requestedAt": "2024-01-05T10:00:01Z",
  "status": "Requested"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Request a PIX Automatico authorization

Requests a recurring-payment authorization as the recipient’s PSP (JDPI 4.3.1). Persists the authorization in the Requested state and returns the JDPI request id. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. The recipient is resolved by the document, or by branch and account: 422 PIX-0143 when they match more than one account, and 422 PIX-0144 when the branch and account belong to a different holder than the document.

POST

pix-automatico

authorizations

curl --request POST \
  --url https://api.example.com/v1/pix-automatico/authorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractNumber": "1234567890ABC",
  "createdDateTime": "2024-01-05T10:00:00.000Z",
  "expirationDateTime": "2024-01-06T10:00:00.000Z",
  "frequency": 1,
  "payer": {
    "account": "0007654321",
    "cpfCnpj": "04623217035",
    "ispb": "00038166",
    "personType": 0,
    "agency": "0001"
  },
  "recipient": {
    "cnpj": "61695227000193",
    "ispb": "04358798",
    "name": "Enel"
  },
  "recurrenceId": "RR0435879820240605njua7shf40o",
  "solicitationDateTime": "2024-01-05T10:00:00.000Z",
  "startDate": "2024-01-10",
  "amount": 110001,
  "contractDesc": "Conta de energia",
  "endDate": "2026-01-10",
  "floorMaxAmount": 55000
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/pix-automatico/authorizations"

	payload := strings.NewReader("{\n  \"contractNumber\": \"1234567890ABC\",\n  \"createdDateTime\": \"2024-01-05T10:00:00.000Z\",\n  \"expirationDateTime\": \"2024-01-06T10:00:00.000Z\",\n  \"frequency\": 1,\n  \"payer\": {\n    \"account\": \"0007654321\",\n    \"cpfCnpj\": \"04623217035\",\n    \"ispb\": \"00038166\",\n    \"personType\": 0,\n    \"agency\": \"0001\"\n  },\n  \"recipient\": {\n    \"cnpj\": \"61695227000193\",\n    \"ispb\": \"04358798\",\n    \"name\": \"Enel\"\n  },\n  \"recurrenceId\": \"RR0435879820240605njua7shf40o\",\n  \"solicitationDateTime\": \"2024-01-05T10:00:00.000Z\",\n  \"startDate\": \"2024-01-10\",\n  \"amount\": 110001,\n  \"contractDesc\": \"Conta de energia\",\n  \"endDate\": \"2026-01-10\",\n  \"floorMaxAmount\": 55000\n}")

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

	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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contractNumber: '1234567890ABC',
    createdDateTime: '2024-01-05T10:00:00.000Z',
    expirationDateTime: '2024-01-06T10:00:00.000Z',
    frequency: 1,
    payer: {
      account: '0007654321',
      cpfCnpj: '04623217035',
      ispb: '00038166',
      personType: 0,
      agency: '0001'
    },
    recipient: {cnpj: '61695227000193', ispb: '04358798', name: 'Enel'},
    recurrenceId: 'RR0435879820240605njua7shf40o',
    solicitationDateTime: '2024-01-05T10:00:00.000Z',
    startDate: '2024-01-10',
    amount: 110001,
    contractDesc: 'Conta de energia',
    endDate: '2026-01-10',
    floorMaxAmount: 55000
  })
};

fetch('https://api.example.com/v1/pix-automatico/authorizations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/pix-automatico/authorizations"

payload = {
    "contractNumber": "1234567890ABC",
    "createdDateTime": "2024-01-05T10:00:00.000Z",
    "expirationDateTime": "2024-01-06T10:00:00.000Z",
    "frequency": 1,
    "payer": {
        "account": "0007654321",
        "cpfCnpj": "04623217035",
        "ispb": "00038166",
        "personType": 0,
        "agency": "0001"
    },
    "recipient": {
        "cnpj": "61695227000193",
        "ispb": "04358798",
        "name": "Enel"
    },
    "recurrenceId": "RR0435879820240605njua7shf40o",
    "solicitationDateTime": "2024-01-05T10:00:00.000Z",
    "startDate": "2024-01-10",
    "amount": 110001,
    "contractDesc": "Conta de energia",
    "endDate": "2026-01-10",
    "floorMaxAmount": 55000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "idReqJdPi": "52c43361-caa1-4ddb-9152-708426a25db3",
  "recurrenceId": "RR0435879820240605njua7shf40o",
  "requestedAt": "2024-01-05T10:00:01Z",
  "status": "Requested"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Body

application/json

contractNumber

string

required

Contract/order identifier (nrContrato).

Pattern: \S

Example:

"1234567890ABC"

createdDateTime

string<date-time>

required

Recurrence creation timestamp (dtHrCriacaoRecorrencia, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the request.

Pattern: \S

Example:

"2024-01-05T10:00:00.000Z"

expirationDateTime

string<date-time>

required

Solicitation expiration timestamp (dtHrExpiracaoSolicitacao, an RFC 3339 date-time; at most 30 days after solicitationDateTime).

Pattern: \S

Example:

"2024-01-06T10:00:00.000Z"

frequency

integer<int64>

required

tpFrequencia (0=Weekly,1=Monthly,2=Quarterly,3=Semiannual,4=Annual).

Example:

1

payer

object

required

The recurrence pagador (account being authorized).

Show child attributes

recipient

object

required

The recurrence recebedor (authorized charging entity).

Show child attributes

recurrenceId

string

required

Unique recurrence id (29-char, format RR...).

Pattern: \S

Example:

"RR0435879820240605njua7shf40o"

solicitationDateTime

string<date-time>

required

Solicitation creation timestamp (dtHrCriacaoSolicitacao, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the request.

Pattern: \S

Example:

"2024-01-05T10:00:00.000Z"

startDate

string

required

First payment date (dtInicialRecorrencia; aaaa-mm-dd).

Pattern: \S

Example:

"2024-01-10"

amount

integer<int64>

Fixed payment amount in centavos (valor; omit/0 for a variable recurrence).

Example:

110001

contractDesc

string

Free-text contract description (descContrato).

Example:

"Conta de energia"

debtor

object

The devedor, sent only when it differs from the payer.

Show child attributes

endDate

string

Last payment date (dtFinalRecorrencia; aaaa-mm-dd).

Example:

"2026-01-10"

floorMaxAmount

integer<int64>

Receiver floor in centavos (pisoValorMaximo).

Example:

55000

Response

Accepted

idReqJdPi

string

required

The JDPI request id (36-char GUID).

Example:

"52c43361-caa1-4ddb-9152-708426a25db3"

recurrenceId

string

required

The recurrence id (echoed).

Example:

"RR0435879820240605njua7shf40o"

requestedAt

string

required

JDPI request timestamp (dtHrReqJdPi, UTC).

Example:

"2024-01-05T10:00:01Z"

status

string

required

The resulting local authorization status.

Example:

"Requested"

Direct participant APIs

Indirect participant APIs

Request a PIX Automatico authorization

Authorizations

Body

Response