Skip to main content
POST
/
addresses
/
pix
Register a PIX destination for a customer.
curl --request POST \
  --url https://api.sandbox.iron.xyz/api/addresses/pix \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'IDEMPOTENCY-KEY: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recipient": {
    "account": {
      "key": "+5511987654321",
      "type": "PHONE"
    },
    "recipient": {
      "family_name": "Turing",
      "given_name": "Alan",
      "type": "Individual"
    },
    "tax_id": "12345678909"
  },
  "label": "<string>"
}
'
{
  "created_at": "2024-01-15T10:30:00.000Z",
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "label": "Primary PIX",
  "recipient": {
    "account": {
      "key": "+5511987654321",
      "type": "PHONE"
    },
    "recipient": {
      "family_name": "Turing",
      "given_name": "Alan",
      "type": "Individual"
    },
    "tax_id": "12345678909"
  },
  "status": "Registered",
  "updated_at": "1970-01-01T00:00:00.000Z"
}

Authorizations

​
X-API-Key
string
header
required

API Key

Headers

​
IDEMPOTENCY-KEY
string
required

a UUID ensuring an address is only registered once

Body

application/json; charset=utf-8

The PIX address registration request

Register PIX Address Request

Request to register a PIX payout destination (Brazil / BRL).

​
customer_id
string<uuid>
required

The customer ID

​
recipient
RecipientPix · object
required

RecipientPix

A PIX payout recipient.

Example:
{
  "account": { "key": "+5511987654321", "type": "PHONE" },
  "recipient": {
    "family_name": "Turing",
    "given_name": "Alan",
    "type": "Individual"
  },
  "tax_id": "12345678909"
}
​
label
string

Optional label for the address

Response

Registration successful

PIX Address

Response containing PIX destination details.

​
created_at
string<date-time>
required

When the address was created

​
customer_id
string<uuid>
required

The customer ID

​
id
string<uuid>
required

The ID of the address

​
recipient
RecipientPix · object
required

RecipientPix

A PIX payout recipient.

Example:
{
  "account": { "key": "+5511987654321", "type": "PHONE" },
  "recipient": {
    "family_name": "Turing",
    "given_name": "Alan",
    "type": "Individual"
  },
  "tax_id": "12345678909"
}
​
status
enum<string>
required

PIX Address Status

Available options:
RegistrationPending,
Registered,
RegistrationFailed
​
updated_at
string<date-time>
required

When the address was last updated

​
label
string

Optional label for the address