SPI API Reference

The SPI API endpoints handle instant payment operations. They are served by the Settlement Service gateway on port 4003, which proxies to the SPI Service on port 4002. All endpoints require JWT authentication.

Base URL: http://localhost:4003/api/v1

Payments

Initiate Payment

Create a new PIX instant payment.

POST /payments

Request Body:

{
  "amount": 150.00,
  "description": "Payment for services",
  "pix_key": "+5511999887766",
  "debtor": {
    "account_number": "123456",
    "branch": "0001",
    "name": "Maria Silva",
    "tax_id": "12345678901"
  },
  "idempotency_key": "unique-client-request-id-123"
}

Request Fields:

Field	Type	Required	Description
amount	decimal	Yes	Payment amount in BRL (0.01 - 999,999,999.99)
description	string	No	Payment description (max 140 chars)
pix_key	string	Yes*	Destination PIX key
creditor_account	object	Yes*	Destination account (alternative to pix_key)
debtor	object	Yes	Debtor (sender) information
idempotency_key	string	Yes	Client-generated unique request ID
priority	string	No	NORM (default) or HIGH

*Either pix_key or creditor_account must be provided.

Response: 201 Created

{
  "payment_id": "pay-a1b2c3d4",
  "end_to_end_id": "E1234567820240115120012345678901",
  "status": "PROCESSING",
  "amount": 150.00,
  "currency": "BRL",
  "description": "Payment for services",
  "debtor": {
    "ispb": "12345678",
    "branch": "0001",
    "account_number": "123456",
    "name": "Maria Silva",
    "tax_id": "***456***01"
  },
  "creditor": {
    "ispb": "87654321",
    "branch": "0002",
    "account_number": "654321",
    "name": "Jo** Si***",
    "tax_id": "***789***02"
  },
  "timestamps": {
    "created_at": "2024-01-15T12:00:00Z",
    "submitted_at": "2024-01-15T12:00:01Z"
  }
}

Payment Statuses:

Status	Description
PROCESSING	Payment created and being processed
SUBMITTED	Sent to BACEN SPI
CONFIRMED	Confirmed by BACEN (funds settled)
REJECTED	Rejected by BACEN
RETURNED	Payment was returned/reversed
FAILED	Processing error

Error Responses:

Status	Code	Description
400	INVALID_AMOUNT	Amount outside allowed range
400	INVALID_KEY	PIX key format is invalid
404	KEY_NOT_FOUND	PIX key not registered in DICT
409	DUPLICATE_PAYMENT	Idempotency key already used
422	INSUFFICIENT_BALANCE	Debtor account has insufficient funds
422	ACCOUNT_BLOCKED	Debtor account is blocked
503	SPI_UNAVAILABLE	BACEN SPI is unreachable

---

Get Payment Details

Retrieve the full details and timeline of a payment.

GET /payments/:payment_id

Response: 200 OK

{
  "payment_id": "pay-a1b2c3d4",
  "end_to_end_id": "E1234567820240115120012345678901",
  "transaction_id": "TXN20240115ABC123",
  "status": "CONFIRMED",
  "amount": 150.00,
  "currency": "BRL",
  "description": "Payment for services",
  "debtor": {
    "ispb": "12345678",
    "branch": "0001",
    "account_number": "123456",
    "name": "Maria Silva",
    "tax_id": "12345678901"
  },
  "creditor": {
    "ispb": "87654321",
    "branch": "0002",
    "account_number": "654321",
    "name": "Joao Silva",
    "tax_id": "98765432102"
  },
  "timestamps": {
    "created_at": "2024-01-15T12:00:00Z",
    "submitted_at": "2024-01-15T12:00:01Z",
    "confirmed_at": "2024-01-15T12:00:02Z"
  },
  "settlement": {
    "window_id": "W20240115-03",
    "settled": true
  },
  "timeline": [
    {
      "event": "CREATED",
      "timestamp": "2024-01-15T12:00:00Z"
    },
    {
      "event": "KEY_RESOLVED",
      "timestamp": "2024-01-15T12:00:00.150Z",
      "details": "Destination resolved via DICT"
    },
    {
      "event": "SUBMITTED_TO_SPI",
      "timestamp": "2024-01-15T12:00:01Z",
      "details": "pacs.008 sent to BACEN"
    },
    {
      "event": "CONFIRMED",
      "timestamp": "2024-01-15T12:00:02Z",
      "details": "pacs.002 ACCC received"
    }
  ]
}

---

List Payments

Retrieve a paginated list of payments with filtering.

GET /payments

Query Parameters:

Parameter	Type	Description
status	string	Filter by payment status
direction	string	inbound or outbound
start_date	datetime	Start of date range (ISO 8601)
end_date	datetime	End of date range (ISO 8601)
min_amount	decimal	Minimum amount filter
max_amount	decimal	Maximum amount filter
account_number	string	Filter by debtor or creditor account
end_to_end_id	string	Search by E2EID
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)
sort	string	Sort field (default: created_at)
order	string	asc or desc (default: desc)

Response: 200 OK

{
  "data": [
    {
      "payment_id": "pay-a1b2c3d4",
      "end_to_end_id": "E1234567820240115120012345678901",
      "status": "CONFIRMED",
      "amount": 150.00,
      "direction": "outbound",
      "creditor_name": "Joao Silva",
      "created_at": "2024-01-15T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 15234,
    "total_pages": 762
  }
}

---

Initiate Return

Return a previously completed payment (full or partial).

POST /payments/:payment_id/return

Request Body:

{
  "amount": 150.00,
  "reason": "MD06",
  "description": "Refund requested by account holder"
}

Return Reason Codes:

Code	Description
MD06	Refund request by original sender
FR01	Fraud
AC03	Invalid creditor account number
AM09	Wrong amount
BE08	Wrong creditor
SL02	Specific service by creditor agent
RR04	Regulatory reason

Response: 201 Created

{
  "return_id": "ret-e5f6g7h8",
  "original_payment_id": "pay-a1b2c3d4",
  "original_e2e_id": "E1234567820240115120012345678901",
  "return_e2e_id": "D1234567820240116090087654321098",
  "amount": 150.00,
  "reason": "MD06",
  "status": "PROCESSING",
  "created_at": "2024-01-16T09:00:00Z"
}

WARNING

Returns must be initiated within 90 days of the original payment. For fraud-related returns (MED), different deadlines apply as defined by BACEN.

---

QR Codes

Generate Static QR Code

Create a reusable PIX QR code.

POST /qrcodes

Request Body:

{
  "type": "STATIC",
  "pix_key": "12345678901",
  "merchant_name": "Loja ABC",
  "merchant_city": "Sao Paulo",
  "amount": null,
  "description": "Pagamento na Loja ABC"
}

Response: 201 Created

{
  "qrcode_id": "qr-i9j0k1l2",
  "type": "STATIC",
  "emv_payload": "00020126580014br.gov.bcb.pix0111123456789015204000053039865802BR5909Loja ABC6009Sao Paulo62070503***6304A1B2",
  "image_url": "/qrcodes/qr-i9j0k1l2/image.png",
  "created_at": "2024-01-15T10:00:00Z"
}

---

Generate Dynamic QR Code

Create a single-use PIX QR code with a specific amount and expiration.

POST /qrcodes

Request Body:

{
  "type": "DYNAMIC",
  "pix_key": "12345678901",
  "merchant_name": "Loja ABC",
  "merchant_city": "Sao Paulo",
  "amount": 299.90,
  "description": "Pedido #12345",
  "expires_in": 3600,
  "payer": {
    "name": "Maria Silva",
    "tax_id": "12345678901"
  }
}

Response: 201 Created

{
  "qrcode_id": "qr-m3n4o5p6",
  "type": "DYNAMIC",
  "emv_payload": "00020126930014br.gov.bcb.pix2571api.example.com/pix/v2/cob/abc123...",
  "image_url": "/qrcodes/qr-m3n4o5p6/image.png",
  "location_url": "https://api.example.com/pix/v2/cob/abc123",
  "amount": 299.90,
  "expires_at": "2024-01-15T11:00:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

---

Get QR Code

GET /qrcodes/:qrcode_id

Returns the QR code details including current payment status for dynamic QR codes.

---

Position

Get Current Position

Retrieve the institution's current settlement position.

GET /position

Response: 200 OK

{
  "position": {
    "available": 50000000.00,
    "reserved": 1500000.00,
    "limit": 100000000.00,
    "utilization_percent": 50.0
  },
  "today": {
    "total_debits": 25000000.00,
    "total_credits": 23500000.00,
    "net": -1500000.00,
    "transaction_count": 45230
  },
  "last_updated": "2024-01-15T12:00:05Z"
}

---

Webhooks

Payment Status Webhook

When a payment status changes, the platform sends a webhook notification to registered URLs.

Webhook Payload:

{
  "event": "payment.confirmed",
  "payment_id": "pay-a1b2c3d4",
  "end_to_end_id": "E1234567820240115120012345678901",
  "status": "CONFIRMED",
  "amount": 150.00,
  "direction": "inbound",
  "timestamp": "2024-01-15T12:00:02Z"
}

Webhook Events:

Event	Description
payment.confirmed	Payment successfully settled
payment.rejected	Payment rejected by BACEN
payment.returned	Payment return completed
payment.received	Inbound payment received
claim.received	Portability/ownership claim received
infraction.received	Infraction report received

Signature Verification:

Each webhook includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body:

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

Verify the signature using your webhook secret to ensure the request originated from FluxiQ PIX.