Process and confirm a Pix transfer (step 2)

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/cashout/process \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "initiationId": "019606a1-3b4c-7d8e-9f01-234567890abc",
  "amount": "100.00"
}
'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/transfers/cashout/process"

	payload := strings.NewReader("{\n  \"initiationId\": \"019606a1-3b4c-7d8e-9f01-234567890abc\",\n  \"amount\": \"100.00\"\n}")

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Account-Id", "<x-account-id>")
	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>',
    'X-Account-Id': '<x-account-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({initiationId: '019606a1-3b4c-7d8e-9f01-234567890abc', amount: '100.00'})
};

fetch('https://api.example.com/spi/v1/transfers/cashout/process', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/spi/v1/transfers/cashout/process"

payload = {
    "initiationId": "019606a1-3b4c-7d8e-9f01-234567890abc",
    "amount": "100.00"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "amount": "100.00",
  "createdAt": "2026-05-06T10:30:00Z",
  "endToEndId": "E12345678202605061030abcdef12345",
  "id": "019606a2-4c5d-7e8f-90a1-345678901bcd",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:30:05Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "aliasId": "<string>",
  "alreadyRefundedAmount": "60.00",
  "currency": "BRL",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Pagamento de aluguel",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "feeCharge": {
    "applied": true,
    "calculationType": "LEDGER",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "LEDGER_FEE",
        "calculationType": "LEDGER",
        "calculationValue": "<string>",
        "creditAccount": "@fees-pix"
      }
    ],
    "netAmount": "100.00",
    "totalAmount": "1.50"
  },
  "initiatedAt": "2026-05-06T10:30:00Z",
  "initiationType": "DICT",
  "ledger": {
    "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
    "revert": {
      "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
      "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
      "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
    },
    "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
    "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
  },
  "metadata": {},
  "paymentType": "PIX",
  "purpose": "IACT",
  "remainingRefundableAmount": "40.00",
  "source": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "urgency": "HIGH"
}

{
  "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-0320",
  "title": "Not Found",
  "status": 404,
  "detail": "Initiation ID does not exist.",
  "code": "PIX-0320"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0322",
  "title": "Conflict",
  "status": 409,
  "detail": "Initiation was already confirmed.",
  "code": "PIX-0322"
}

{
  "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-0321",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Initiation has expired.",
  "code": "PIX-0321"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0324",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0324"
}

{
  "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"
  }
}

Process and confirm a Pix transfer (step 2)

Confirms a previously initiated transfer, debits the source account, and submits the Pix payment for processing. When the submission fails without proof that the order never left (a timeout or a 5xx), the debit is kept and the call answers 201 with status PROCESSING: read the transfer for the outcome. A 502 PIX-0325 answers only an order that provably was not sent, once the reversal of the debit is recorded. When the reversal is not recorded, the call answers 500.

POST

transfers

cashout

process

Process and confirm a Pix transfer (step 2)

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/cashout/process \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "initiationId": "019606a1-3b4c-7d8e-9f01-234567890abc",
  "amount": "100.00"
}
'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/transfers/cashout/process"

	payload := strings.NewReader("{\n  \"initiationId\": \"019606a1-3b4c-7d8e-9f01-234567890abc\",\n  \"amount\": \"100.00\"\n}")

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Account-Id", "<x-account-id>")
	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>',
    'X-Account-Id': '<x-account-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({initiationId: '019606a1-3b4c-7d8e-9f01-234567890abc', amount: '100.00'})
};

fetch('https://api.example.com/spi/v1/transfers/cashout/process', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/spi/v1/transfers/cashout/process"

payload = {
    "initiationId": "019606a1-3b4c-7d8e-9f01-234567890abc",
    "amount": "100.00"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "amount": "100.00",
  "createdAt": "2026-05-06T10:30:00Z",
  "endToEndId": "E12345678202605061030abcdef12345",
  "id": "019606a2-4c5d-7e8f-90a1-345678901bcd",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:30:05Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "aliasId": "<string>",
  "alreadyRefundedAmount": "60.00",
  "currency": "BRL",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Pagamento de aluguel",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "feeCharge": {
    "applied": true,
    "calculationType": "LEDGER",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "LEDGER_FEE",
        "calculationType": "LEDGER",
        "calculationValue": "<string>",
        "creditAccount": "@fees-pix"
      }
    ],
    "netAmount": "100.00",
    "totalAmount": "1.50"
  },
  "initiatedAt": "2026-05-06T10:30:00Z",
  "initiationType": "DICT",
  "ledger": {
    "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
    "revert": {
      "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
      "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
      "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
    },
    "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
    "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
  },
  "metadata": {},
  "paymentType": "PIX",
  "purpose": "IACT",
  "remainingRefundableAmount": "40.00",
  "source": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "urgency": "HIGH"
}

{
  "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-0320",
  "title": "Not Found",
  "status": 404,
  "detail": "Initiation ID does not exist.",
  "code": "PIX-0320"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0322",
  "title": "Conflict",
  "status": 409,
  "detail": "Initiation was already confirmed.",
  "code": "PIX-0322"
}

{
  "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-0321",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Initiation has expired.",
  "code": "PIX-0321"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0324",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0324"
}

{
  "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"
  }
}

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

X-Account-Id

string

requerido

Source account UUID

Ejemplo:

"019606a1-3b4c-7d8e-9f01-234567890abc"

X-End-To-End-Id

string

Optional caller-supplied 32-char BACEN endToEndId, accepted for MANUAL initiations only (omit it to let SPI generate one). It is not the idempotency key -- that is X-Idempotency. A DICT or QR_CODE initiation already fixed its endToEndId at initiate (returned as endToEndId) and process reuses it automatically: for those, omit this header; sending it, even with the same value, is refused (PIX-0300) while the initiation is pending -- a retry of a process that already concluded (initiation CONFIRMED) returns the existing transfer, without the header or with a well-formed one.

Ejemplo:

"E12345678202605061030abcdef12345"

Cuerpo

application/json

initiationId

string

requerido

Initiation UUID returned by step 1

Ejemplo:

"019606a1-3b4c-7d8e-9f01-234567890abc"

amount

string

Confirmed amount (required unless locked by a fixed QR amount; a dynamic charge the payer may change only suggests one)

Ejemplo:

"100.00"

Respuesta

Created

amount

string

requerido

Ejemplo:

"100.00"

createdAt

string<date-time>

requerido

Ejemplo:

"2026-05-06T10:30:00Z"

endToEndId

string

requerido

Ejemplo:

"E12345678202605061030abcdef12345"

string

requerido

Ejemplo:

"019606a2-4c5d-7e8f-90a1-345678901bcd"

status

string

requerido

Ejemplo:

"COMPLETED"

type

string

requerido

Ejemplo:

"OUTBOUND"

updatedAt

string<date-time>

requerido

Ejemplo:

"2026-05-06T10:30:05Z"

accountId

string

Ejemplo:

"019606a0-1a2b-7c3d-8e4f-567890123abc"

aliasId

string

alreadyRefundedAmount

string

Cross-mechanism settled and reserved refund amount. Returned only for INBOUND transfers.

Ejemplo:

"60.00"

currency

string

Ejemplo:

"BRL"

deletedAt

string<date-time>

description

string

Ejemplo:

"Pagamento de aluguel"

destination

object

Show child attributes

feeCharge

object

Fee the ledger reported on the transfer. Absent when the ledger's fee answer was not recorded for this transfer (an error logged at the time, or a transfer created before fees were read back); {"applied": false} when the ledger reported that no fee was charged; the full object when it charged one.

Show child attributes

initiatedAt

string<date-time>

Ejemplo:

"2026-05-06T10:30:00Z"

initiationType

string

Ejemplo:

"DICT"

ledger

object

Show child attributes

metadata

object

Show child attributes

paymentType

string

Ejemplo:

"PIX"

purpose

string

Ejemplo:

"IACT"

remainingRefundableAmount

string

Amount minus alreadyRefundedAmount. Returned only for INBOUND transfers and can be negative.

Ejemplo:

"40.00"

source

object

Show child attributes

urgency

string

Ejemplo:

"HIGH"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Process and confirm a Pix transfer (step 2)

Autorizaciones

Encabezados

Cuerpo

Respuesta