Saltar al contenido principal
POST

Autorizaciones

Authorization
string
header
requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency
string
requerido

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 ruta

fact_type
enum<string>
requerido

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.

Opciones disponibles:
OUTBOUND_FRAUD_REFUSAL,
OUTSIDE_SPI_SETTLEMENT,
OUTSIDE_SPI_REFUND,
DICT_SCREEN_STEP
Ejemplo:

"OUTSIDE_SPI_REFUND"

client_request_id
string
requerido

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

"cb-2026-10-000017"

Cuerpo

application/json

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

amount
string
requerido

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

"89.90"

clientRequestId
string
requerido

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

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

"osp-2026-10-004512"

endToEndId
string
requerido

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

"E12345678202610311545f6e5d4c3b2a"

factType
enum<string>
requerido

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

Opciones disponibles:
OUTSIDE_SPI_SETTLEMENT
Ejemplo:

"OUTSIDE_SPI_SETTLEMENT"

payerIspb
string
requerido

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

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

"12345678"

purpose
enum<string>
requerido

Transaction purpose, the layout's FinalidadeTransacoes.

Opciones disponibles:
IPAY,
OTHR,
GSCB,
AUTOMATIC
Ejemplo:

"IPAY"

receiverIspb
string
requerido

ISPB of the receiver's participant.

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

"12345678"

settledAt
string<date-time>
requerido

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

Ejemplo:

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

Ejemplo:

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

"0.00"

fraudSuspected
boolean

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

Ejemplo:

false

highPriority
boolean

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

Ejemplo:

true

initiationChannel
enum<string>

Channel the payer used (APIX002).

Opciones disponibles:
APP,
INTERNET_BANKING,
CALL_CENTER,
ATM,
BRANCH
Ejemplo:

"APP"

initiationMechanism
enum<string>

How the payment was initiated (APIX002).

Opciones disponibles:
KEY,
DYNAMIC_QR,
STATIC_QR,
PAYMENT_INITIATOR,
MANUAL
Ejemplo:

"KEY"

initiationProcedure
enum<string>

How the payment data was entered (APIX002).

Opciones disponibles:
MANUAL,
PRE_STORED
Ejemplo:

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

Ejemplo:

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

payerPersonType
enum<string>

Payer's person type (APIX002).

Opciones disponibles:
NATURAL_PERSON,
LEGAL_PERSON
Ejemplo:

"NATURAL_PERSON"

paymentInitiatorIspb
string

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

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

"87654321"

receiverPersonType
enum<string>

Receiver's person type (APIX002).

Opciones disponibles:
NATURAL_PERSON,
LEGAL_PERSON
Ejemplo:

"LEGAL_PERSON"

scheduled
boolean

Whether the payment was scheduled; absent is false.

Ejemplo:

false

Respuesta

OK

clientRequestId
string
requerido

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

Ejemplo:

"cb-2026-10-000017"

factId
string<uuid>
requerido

Identifier of this version of the fact.

Ejemplo:

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

factType
string
requerido

Fact type, as in the path.

Ejemplo:

"OUTSIDE_SPI_REFUND"

payload
any
requerido

The fact body as recorded.

period
string
requerido

Reference month the fact counts in, YYYY-MM.

Ejemplo:

"2026-10"

version
integer<int64>
requerido

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

Ejemplo:

1