> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagsmile.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm PIX Transfer by QR Code

> Submit a PIX transfer from a QR-initiation reference.

Submit payment using a valid reference created by the QR-code initiation route.

### Endpoint

```
POST /v3/transfers/pix/qr-code-confirm
```

### Authentication and target

Use an ACCOUNT credential for its bound account, or a USER credential with both `X-ISPB` and `X-Account-Number`. If an ACCOUNT credential sends those headers, both must be present and must match its bound account. PLATFORM credentials are not accepted. All requests require the standard HMAC-SHA256 headers.

The curl example below uses an ACCOUNT credential bound to the operated account, so it omits `X-ISPB` and `X-Account-Number`. If `X-Client-ID` identifies a USER credential, add both target headers and include their exact trimmed values in the canonical header set before calculating `X-Signature`.

### Request body

| Field               | Required | Type   | Validation                                                                     |
| ------------------- | -------- | ------ | ------------------------------------------------------------------------------ |
| `ref_id`            | Yes      | string | Must exist in the five-minute QR cache and belong to this account.             |
| `merchant_order_id` | Yes      | string | Starts with current UTC YYMMDD using the ±1-hour allowance.                    |
| `amount`            | Yes      | string | Positive decimal with at most two places. A fixed QR amount cannot be changed. |
| `currency`          | No       | string | Accepted but ignored; the service sends BRL.                                   |
| `memo`              | No       | string | Forwarded to processing.                                                       |

### Success data

`merchant_order_id`, `txn_id`, and numeric `txn_status`. The current mapper does not populate declared payer and payee fields.

### Behavior and validation

For a fixed-amount QR, the request amount must equal the cached amount. A QR without an embedded amount can receive one at confirmation. The reference is removed on success; a tested upstream payload failure retains it. No endpoint-specific idempotency key exists.

### Errors

Every call can fail for missing or invalid signature headers, an expired timestamp, nonce replay, an invalid body hash or signature, insufficient permission, or a downstream service error. Endpoint-specific errors include:

* `4000` for missing required fields.
* `4002` for an invalid amount or merchant order format.
* `400` for a stale merchant order date.
* `4003012` for a missing, expired, or invalid reference.
* `4004003` when the reference belongs to another account.
* `4003014` for payment failure, plus mapped provider errors such as insufficient funds.
* `400` when a fixed QR amount is changed.

### Example request

```bash theme={null}
curl --request POST "${BASE_URL}/v3/transfers/pix/qr-code-confirm" \
  --header "Content-Type: application/json" \
  --header "X-Client-ID: ${CLIENT_ID}" \
  --header "X-Timestamp: ${TIMESTAMP_MS}" \
  --header "X-Nonce: ${NONCE}" \
  --header "X-Content-Hash: ${CONTENT_HASH}" \
  --header "X-Signature: ${SIGNATURE}" \
  --data '{"ref_id":"66666666-7777-4888-8999-aaaaaaaaaaaa","merchant_order_id":"<CURRENT_UTC_YYMMDD>-demo-qr-001","amount":"12.34","currency":"USD","memo":"Demo QR payment"}'
```

### Example response

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "merchant_order_id": "<CURRENT_UTC_YYMMDD>-demo-qr-001",
    "txn_id": "demo-pix-txn-002",
    "txn_status": 1
  },
  "time": 1767225600000
}
```