Settle a refund with an aggregated block devolution (Phase 1)

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {'X-Idempotency': '<x-idempotency>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "alreadySettled": "50.00",
  "blocksStatus": "SETTLING",
  "operationType": "ROOT",
  "originalAmount": "200.00",
  "refundId": "018f8c1d-1234-7abc-9def-000000000010",
  "status": "OPEN",
  "blocks": [
    {
      "amount": "120.00",
      "lockId": "b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f",
      "spiBlockId": "7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
    }
  ],
  "endToEndId": "<string>",
  "settleAmount": "150.00",
  "settleReason": "FR01",
  "settleType": "REFUND",
  "settled": false,
  "surplusAmount": "50.00"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The Idempotency-Key header is required for this operation and must be within the accepted length."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0005",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to perform this operation.",
  "code": "PIX-0005"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0011",
  "title": "Not Found",
  "status": 404,
  "detail": "No entity was found for the given ID. Please make sure to use the correct ID.",
  "code": "PIX-0011"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0012",
  "title": "Conflict",
  "status": 409,
  "detail": "The entity already exists or conflicts with an existing resource.",
  "code": "PIX-0012"
}

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The Idempotency-Key was already used with a different request."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0013",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The operation could not be processed due to a business rule violation.",
  "code": "PIX-0013"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0141",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "internal error",
  "code": "PIX-0141"
}

{
  "code": "ERR-0001",
  "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"
  }
}

Settle a refund with an aggregated block devolution (Phase 1)

Initiates exactly one aggregated devolution for all PENDING blocks linked to the refund infraction report and changes those blocks together to SETTLING. Processing is selected automatically from the infraction operation type and contested transaction format. The refund remains OPEN during this phase. The request has no body. A successful SPI response reports SETTLING, or SETTLED for an idempotent replay; rejected or unexpected outcomes return an error. Only the requesting participant tenant may settle its own refund.

POST

dict

refunds

{id}

settle

Settle a refund with an aggregated block devolution (Phase 1)

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {'X-Idempotency': '<x-idempotency>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "alreadySettled": "50.00",
  "blocksStatus": "SETTLING",
  "operationType": "ROOT",
  "originalAmount": "200.00",
  "refundId": "018f8c1d-1234-7abc-9def-000000000010",
  "status": "OPEN",
  "blocks": [
    {
      "amount": "120.00",
      "lockId": "b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f",
      "spiBlockId": "7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
    }
  ],
  "endToEndId": "<string>",
  "settleAmount": "150.00",
  "settleReason": "FR01",
  "settleType": "REFUND",
  "settled": false,
  "surplusAmount": "50.00"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The Idempotency-Key header is required for this operation and must be within the accepted length."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0005",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to perform this operation.",
  "code": "PIX-0005"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0011",
  "title": "Not Found",
  "status": 404,
  "detail": "No entity was found for the given ID. Please make sure to use the correct ID.",
  "code": "PIX-0011"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0012",
  "title": "Conflict",
  "status": 409,
  "detail": "The entity already exists or conflicts with an existing resource.",
  "code": "PIX-0012"
}

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The Idempotency-Key was already used with a different request."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0013",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The operation could not be processed due to a business rule violation.",
  "code": "PIX-0013"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0141",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "internal error",
  "code": "PIX-0141"
}

{
  "code": "ERR-0001",
  "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"
  }
}

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. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

X-Correlation-Id

string

Best-effort business correlation id (observability only; never fabricated).

Parámetros de ruta

string

requerido

Refund internal ID (UUID format)

Ejemplo:

"018f8c1d-1234-7abc-9def-000000000010"

Respuesta

Accepted

alreadySettled

string

requerido

Ejemplo:

"50.00"

blocksStatus

enum<string>

requerido

Opciones disponibles:

SETTLING,

PENDING,

SETTLED

Ejemplo:

"SETTLING"

operationType

enum<string>

requerido

Opciones disponibles:

ROOT,

SUBSEQUENT,

UNKNOWN

Ejemplo:

"ROOT"

originalAmount

string

requerido

Ejemplo:

"200.00"

refundId

string

requerido

Ejemplo:

"018f8c1d-1234-7abc-9def-000000000010"

status

enum<string>

requerido

Opciones disponibles:

OPEN,

CLOSED,

CANCELLED

Ejemplo:

"OPEN"

blocks

object[] | null

Show child attributes

endToEndId

string

settleAmount

string

Ejemplo:

"150.00"

settleReason

string

Ejemplo:

"FR01"

settleType

enum<string>

Opciones disponibles:

REFUND,

MANUAL

Ejemplo:

"REFUND"

settled

boolean

Ejemplo:

false

surplusAmount

string

Ejemplo:

"50.00"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

Manejo de errores

Settle a refund with an aggregated block devolution (Phase 1)

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta