Confirm the aggregated settlement (liquidation — Phase 2)

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle/confirm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "endToEndId": "D12345678202601011200abcdef01234",
  "failureReason": "<string>",
  "result": "SUCCESS"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"endToEndId\": \"D12345678202601011200abcdef01234\",\n  \"failureReason\": \"<string>\",\n  \"result\": \"SUCCESS\"\n}")

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    endToEndId: 'D12345678202601011200abcdef01234',
    failureReason: '<string>',
    result: 'SUCCESS'
  })
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle/confirm', 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/confirm"

payload = {
    "endToEndId": "D12345678202601011200abcdef01234",
    "failureReason": "<string>",
    "result": "SUCCESS"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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>",
  "failureReason": {
    "message": "falha no Midaz ao liberar o bloqueio"
  },
  "settleAmount": "150.00",
  "settleReason": "FR01",
  "settleType": "REFUND",
  "settled": false,
  "surplusAmount": "50.00"
}

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

{
  "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 X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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": "<string>",
  "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"
  }
}

Confirm the aggregated settlement (liquidation — Phase 2)

Reports or checks the network outcome of the aggregated devolution. When result=SUCCESS, the group blocks change to SETTLED and the response includes the aggregated settlement facts: effective refunded amount, aggregated end-to-end ID, already-settled and surplus amounts, and settlement type and reason. When result=FAILED, the blocks return to PENDING and those facts remain null, except that a group whose surplus was already returned is refused with 409 PIX-0656 and stays SETTLING. Omitting result checks the current group state without changing it. The refund remains OPEN until it is closed separately. result, when provided, must be SUCCESS or FAILED; endToEndId is required for SUCCESS, and a SUCCESS whose endToEndId is not the one of the group’s devolution is refused with 409 PIX-0012 and changes nothing. The refund is scoped to the authenticated tenant’s organization.

POST

dict

refunds

{id}

settle

confirm

Confirm the aggregated settlement (liquidation — Phase 2)

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle/confirm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "endToEndId": "D12345678202601011200abcdef01234",
  "failureReason": "<string>",
  "result": "SUCCESS"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"endToEndId\": \"D12345678202601011200abcdef01234\",\n  \"failureReason\": \"<string>\",\n  \"result\": \"SUCCESS\"\n}")

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    endToEndId: 'D12345678202601011200abcdef01234',
    failureReason: '<string>',
    result: 'SUCCESS'
  })
};

fetch('https://api.example.com/dict-hub/v1/dict/refunds/{id}/settle/confirm', 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/confirm"

payload = {
    "endToEndId": "D12345678202601011200abcdef01234",
    "failureReason": "<string>",
    "result": "SUCCESS"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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>",
  "failureReason": {
    "message": "falha no Midaz ao liberar o bloqueio"
  },
  "settleAmount": "150.00",
  "settleReason": "FR01",
  "settleType": "REFUND",
  "settled": false,
  "surplusAmount": "50.00"
}

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

{
  "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 X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "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": "<string>",
  "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"
  }
}

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. Resending the same key and request within 1 hour returns the original response, its status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, path or body, or while the first request runs, 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 caminho

string

obrigatório

Refund internal ID (UUID format)

Exemplo:

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

Corpo

application/json

endToEndId

string

Exemplo:

"D12345678202601011200abcdef01234"

failureReason

string

result

enum<string>

Opções disponíveis:

SUCCESS,

FAILED

Exemplo:

"SUCCESS"

Resposta

alreadySettled

string

obrigatório

Exemplo:

"50.00"

blocksStatus

enum<string>

obrigatório

Opções disponíveis:

SETTLING,

PENDING,

SETTLED

Exemplo:

"SETTLING"

operationType

enum<string>

obrigatório

Opções disponíveis:

ROOT,

SUBSEQUENT,

UNKNOWN

Exemplo:

"ROOT"

originalAmount

string

obrigatório

Exemplo:

"200.00"

refundId

string

obrigatório

Exemplo:

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

status

enum<string>

obrigatório

Opções disponíveis:

OPEN,

CLOSED,

CANCELLED

Exemplo:

"OPEN"

blocks

object[] | null

Show child attributes

endToEndId

string

failureReason

object

Show child attributes

settleAmount

string

Exemplo:

"150.00"

settleReason

string

Exemplo:

"FR01"

settleType

enum<string>

Opções disponíveis:

REFUND,

MANUAL

Exemplo:

"REFUND"

settled

boolean

Exemplo:

false

surplusAmount

string

Exemplo:

"50.00"

DICT e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

API de Pix Automático

Tratamento de erros

Confirm the aggregated settlement (liquidation — Phase 2)

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta