Pular para o conteúdo principal
POST

Autorizações

Authorization
string
header
obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency
string
obrigatório

REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

Parâmetros de caminho

fact_type
enum<string>
obrigatório

Fact type, the same value as the factType of the body. One of OUTSIDE_SPI_SETTLEMENT, OUTSIDE_SPI_REFUND, OUTBOUND_FRAUD_REFUSAL or DICT_SCREEN_STEP. Any other value is refused.

Opções disponíveis:
OUTBOUND_FRAUD_REFUSAL,
OUTSIDE_SPI_SETTLEMENT,
OUTSIDE_SPI_REFUND,
DICT_SCREEN_STEP
Exemplo:

"OUTSIDE_SPI_REFUND"

client_request_id
string
obrigatório

clientRequestId of the fact to correct. The fact is addressed by the client key, not by factId: each version is its own row with its own factId, while the client key is stable across versions.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9._:-]+$
Exemplo:

"cb-2026-10-000017"

Corpo

application/json

Fact body, one schema per fact type chosen by factType.

amount
string
obrigatório

Amount in BRL, greater than 0.00, up to 13 integer digits and exactly two decimal places.

Pattern: ^[0-9]{1,13}\.[0-9]{2}$
Exemplo:

"89.90"

clientRequestId
string
obrigatório

Client key of the fact, unique per fact type and tenant.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9._:-]+$
Exemplo:

"osp-2026-10-004512"

endToEndId
string
obrigatório

End-to-end id of the transaction, E prefix; one current fact per end-to-end id (409 PIX-0725).

Pattern: ^E[0-9A-Z]{8}[0-9]{12}[A-Za-z0-9]{11}$
Exemplo:

"E12345678202610311545f6e5d4c3b2a"

factType
enum<string>
obrigatório

Fact type; must equal the path fact_type (422 PIX-0723).

Opções disponíveis:
OUTSIDE_SPI_SETTLEMENT
Exemplo:

"OUTSIDE_SPI_SETTLEMENT"

payerIspb
string
obrigatório

ISPB of the payer's participant. When it is the tenant's own ISPB, acceptedAt and payerNotifiedAt are required.

Pattern: ^[0-9A-Z]{8}$
Exemplo:

"12345678"

purpose
enum<string>
obrigatório

Transaction purpose, the layout's FinalidadeTransacoes.

Opções disponíveis:
IPAY,
OTHR,
GSCB,
AUTOMATIC
Exemplo:

"IPAY"

receiverIspb
string
obrigatório

ISPB of the receiver's participant.

Pattern: ^[0-9A-Z]{8}$
Exemplo:

"12345678"

settledAt
string<date-time>
obrigatório

Settlement instant, RFC 3339; its month in America/Sao_Paulo is the reference month, from 2020-11 through the current month (400 PIX-0003).

Exemplo:

"2026-10-31T15:45:10.958Z"

acceptedAt
string<date-time>

Instant the payer's participant accepted the order. Required, and never null, when payerIspb is the tenant's ISPB; may be absent otherwise.

Exemplo:

"2026-10-31T15:45:10.412Z"

cashAmount
string

Cash part of the amount, absent as 0.00: zero for IPAY and AUTOMATIC, the whole amount for OTHR, more than zero and less than the amount for GSCB; otherwise 400 PIX-0003.

Pattern: ^[0-9]{1,13}\.[0-9]{2}$
Exemplo:

"0.00"

fraudSuspected
boolean

Whether fraud was suspected (APIX002); absent is false. When true, the settlement stays out of the outside-SPI times.

Exemplo:

false

highPriority
boolean

Neither scheduled, AUTOMATIC nor fraudSuspected. Absent is derived from those three; true with any of them is 400 PIX-0003.

Exemplo:

true

initiationChannel
enum<string>

Channel the payer used (APIX002).

Opções disponíveis:
APP,
INTERNET_BANKING,
CALL_CENTER,
ATM,
BRANCH
Exemplo:

"APP"

initiationMechanism
enum<string>

How the payment was initiated (APIX002).

Opções disponíveis:
KEY,
DYNAMIC_QR,
STATIC_QR,
PAYMENT_INITIATOR,
MANUAL
Exemplo:

"KEY"

initiationProcedure
enum<string>

How the payment data was entered (APIX002).

Opções disponíveis:
MANUAL,
PRE_STORED
Exemplo:

"MANUAL"

payerNotifiedAt
string<date-time> | null

Instant the payer was notified of the result. Required and not null when payerIspb is the tenant's ISPB, not before acceptedAt and at most 999999.99 s after it (400 PIX-0003); may be absent or null otherwise.

Exemplo:

"2026-10-31T15:45:11.204Z"

payerPersonType
enum<string>

Payer's person type (APIX002).

Opções disponíveis:
NATURAL_PERSON,
LEGAL_PERSON
Exemplo:

"NATURAL_PERSON"

paymentInitiatorIspb
string

ISPB of the payment initiator; only with initiationMechanism PAYMENT_INITIATOR, otherwise 400 PIX-0003.

Pattern: ^[0-9A-Z]{8}$
Exemplo:

"87654321"

receiverPersonType
enum<string>

Receiver's person type (APIX002).

Opções disponíveis:
NATURAL_PERSON,
LEGAL_PERSON
Exemplo:

"LEGAL_PERSON"

scheduled
boolean

Whether the payment was scheduled; absent is false.

Exemplo:

false

Resposta

OK

clientRequestId
string
obrigatório

The participant's key of the fact, unique per tenant and fact type.

Exemplo:

"cb-2026-10-000017"

factId
string<uuid>
obrigatório

Identifier of this version of the fact.

Exemplo:

"0193a7c2-5d4e-7f10-a2b3-c4d5e6f7a8b9"

factType
string
obrigatório

Fact type, as in the path.

Exemplo:

"OUTSIDE_SPI_REFUND"

payload
any
obrigatório

The fact body as recorded.

period
string
obrigatório

Reference month the fact counts in, YYYY-MM.

Exemplo:

"2026-10"

version
integer<int64>
obrigatório

Version of the fact: 1 when recorded, one more per correction.

Exemplo:

1