Skip to main content
POST

Authorizations

Authorization
string
header
required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency
string
required

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

Path Parameters

fact_type
enum<string>
required

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.

Available options:
OUTBOUND_FRAUD_REFUSAL,
OUTSIDE_SPI_SETTLEMENT,
OUTSIDE_SPI_REFUND,
DICT_SCREEN_STEP
Example:

"OUTSIDE_SPI_REFUND"

client_request_id
string
required

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._:-]+$
Example:

"cb-2026-10-000017"

Body

application/json

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

amount
string
required

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}$
Example:

"89.90"

clientRequestId
string
required

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

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

"osp-2026-10-004512"

endToEndId
string
required

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}$
Example:

"E12345678202610311545f6e5d4c3b2a"

factType
enum<string>
required

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

Available options:
OUTSIDE_SPI_SETTLEMENT
Example:

"OUTSIDE_SPI_SETTLEMENT"

payerIspb
string
required

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

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

"12345678"

purpose
enum<string>
required

Transaction purpose, the layout's FinalidadeTransacoes.

Available options:
IPAY,
OTHR,
GSCB,
AUTOMATIC
Example:

"IPAY"

receiverIspb
string
required

ISPB of the receiver's participant.

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

"12345678"

settledAt
string<date-time>
required

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

Example:

"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.

Example:

"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}$
Example:

"0.00"

fraudSuspected
boolean

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

Example:

false

highPriority
boolean

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

Example:

true

initiationChannel
enum<string>

Channel the payer used (APIX002).

Available options:
APP,
INTERNET_BANKING,
CALL_CENTER,
ATM,
BRANCH
Example:

"APP"

initiationMechanism
enum<string>

How the payment was initiated (APIX002).

Available options:
KEY,
DYNAMIC_QR,
STATIC_QR,
PAYMENT_INITIATOR,
MANUAL
Example:

"KEY"

initiationProcedure
enum<string>

How the payment data was entered (APIX002).

Available options:
MANUAL,
PRE_STORED
Example:

"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.

Example:

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

payerPersonType
enum<string>

Payer's person type (APIX002).

Available options:
NATURAL_PERSON,
LEGAL_PERSON
Example:

"NATURAL_PERSON"

paymentInitiatorIspb
string

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

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

"87654321"

receiverPersonType
enum<string>

Receiver's person type (APIX002).

Available options:
NATURAL_PERSON,
LEGAL_PERSON
Example:

"LEGAL_PERSON"

scheduled
boolean

Whether the payment was scheduled; absent is false.

Example:

false

Response

OK

clientRequestId
string
required

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

Example:

"cb-2026-10-000017"

factId
string<uuid>
required

Identifier of this version of the fact.

Example:

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

factType
string
required

Fact type, as in the path.

Example:

"OUTSIDE_SPI_REFUND"

payload
any
required

The fact body as recorded.

period
string
required

Reference month the fact counts in, YYYY-MM.

Example:

"2026-10"

version
integer<int64>
required

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

Example:

1