Crie e pague um pedido com custódia

A funcionalidade de custódia proporciona maior segurança nas transações ao bloquear temporariamente os lançamentos de um pedido. Esse bloqueio só é liberado após a confirmação da entrega pelo vendedor e/ou comprador. Também conhecida como compra garantida ou pagamento em garantia, essa funcionalidade envolve a retenção do saldo do vendedor por um período específico para assegurar que a entrega do produto ou serviço foi realizada conforme o esperado.

Benefícios da custódia

Para Compradores: Segurança de que o valor associado ao pagamento não será liberado até que estejam satisfeitos com o que receberam.
Para Vendedores: Garantia de que o valor está reservado e será pago assim que o acordo for cumprido.

📘
Informações básicas sobre divisão de pagamento
Caso você ainda não tenha criado pagamentos com divisão de pagamentos anteriormente, ou procura entender melhor como essa operação funciona, explore os seguintes conteúdos antes de testar o o processo de criar um pedido de divisão de pagamento com custódia:

Como utilizar a divisão do pagamento

Crie e pague um pedido com divisão do pagamento

Processo de criação do pedido

A inclusão da custódia em uma transação de divisão de pagamento é opcional. Depois da criação de um pedido com a opção de custódia, você deve realizar a liberação da custódia. A liberação é automática depois do vencimento do prazo, mas você também pode realizar a liberação utilizando o endpoint Liberar divisão de pagamento com custódia.

Regras de utilização

As seguintes regras se aplicam quando você cria um pedido com custódia:

Prazo Máximo: O prazo máximo para liberação da custódia é de:
- 180 dias: Quando não for informado o prazo da liberação na criação do pedido.
- 365 dias: Sendo este o prazo máximo que pode ser definido no campo scheduled.
Após esse prazo, a transação será liberada automaticamente.
Liberação por Data: Para informar a data desejada para liberação da custódia, utilize o padrão ISO 8601 com indicação de fuso horário. Considere o seguinte exemplo 2025-10-19T12:14:49.216-03:00:
- 2025-10-19: representa o dia 19 de outubro de 2025.
- T: separa a data da hora.
- 12:14:49.216: indica o horário local (12h14min49s e 216 milissegundos).
- -03:00: indica o deslocamento em relação ao UTC (Tempo Universal Coordenado). Nesse caso, UTC-3 corresponde ao fuso horário de Brasília.
Caso opte por não aguardar a liberação automática da custódia, a qualquer momento você pode realizar a liberação através do endpoint Liberar divisão de pagamento com custódia .

Criando o pedido

Para criar e pagar um pedido de divisão de pagamento com custódia, você utilizará o endpoint Criar Pedido. Você deverá informar:

Dados do pedido.
Informações do método de pagamento através do objeto charges. Cada método de pagamento pode requerer que você forneça diferentes informações. Acesse a página de Casos de Uso para obter mais informações sobre cada método de pagamento.
Informações sobre como a divisão do pagamento deve ser executada através do objeto charges.split. Para mais informações acesse Como utilizar a divisão do pagamento e Crie e pague um pedido com divisão do pagamento.
Informe que o pedido utilizará a funcionalidade de custódia definindo splits.receivers.configurations.custody.apply = true.

Para habilitar o bloqueio de valores (custódia) em determinados recebedores, é necessário incluir a seguinte configuração no array receivers:

Defina configurations.custody.apply = true para cada recebedor que deve ter o valor bloqueado.
Caso custody.apply esteja como false ou não seja informado, os valores atribuídos a esse recebedor não serão bloqueados.

O exemplo a seguir ilustra um objeto split com dois recebedores. Observe que o objeto configuration é incluído individualmente em cada item do array receivers.

{
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": {
          "id": "ACCO_99999999-9999-9999-9999-999999999999"
        },
        "amount": {
          "value": 10
        },
        "reason": "Receiver 1",
        "configurations": {
          "custody": {
            "apply": true,
            "release": {
              "scheduled": "2025-09-17T12:14:49.216-03:00"
            }
          }
        }
      },
      {
        "account": {
          "id": "ACCO_00000000-0000-0000-0000-000000000000"
        },
        "amount": {
          "value": 90
        },
        "reason": "Receiver 2",
        "configurations": {
          "custody": {
            "apply": false
          }
        }
      }
    ]
  },
  "notification_urls": [
    "https://webhook.site/1904a76e-0024-4f16-a8d6-57ea49aa3fc4"
  ],
  "metadata": {
    "Exemplo": "Aceita qualquer informação"
  }
}

Abaixo você encontra um exemplo de requisição utilizando o endpoint Criar pedido com divisão do pagamento e a opção de custódia utilizando cartão de crédito como meio de pagamento.

curl --location 'https://sandbox.api.pagseguro.com/orders' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 1.0' \
  --header 'Authorization: Bearer token' \
  --data-raw '{
    "reference_id": "teste split com custodia",
    "customer": {
      "name": "Comprador de Teste",
      "email": "comprador@email.com",
      "tax_id": "08843079646",
      "phones": [
        {
          "country": "55",
          "area": "11",
          "number": "999999999",
          "type": "MOBILE"
        }
      ]
    },
    "items": [
      {
        "reference_id": "item teste 1",
        "name": "Placa mae",
        "quantity": 1,
        "unit_amount": 400000
      },
      {
        "reference_id": "item teste 2",
        "name": "SSD",
        "quantity": 1,
        "unit_amount": 80000
      },
      {
        "reference_id": "item teste 3",
        "name": "Processador",
        "quantity": 1,
        "unit_amount": 300000
      },
      {
        "reference_id": "item teste 4",
        "name": "Fonte",
        "quantity": 1,
        "unit_amount": 80000
      }
    ],
    "shipping": {
      "address": {
        "street": "Rua do teste",
        "number": "123",
        "complement": "apto 12",
        "locality": "Pinheiros",
        "city": "São Paulo",
        "region_code": "SP",
        "country": "BRA",
        "postal_code": "12345678"
      }
    },
    "notification_urls": [
      "https://webhook.site/858c9ab7-4754-40ed-8fcc-8aae967e50e4"
    ],
    "charges": [
      {
        "reference_id": "Validacao Split com custodia",
        "description": "payload de testes com custodia",
        "amount": {
          "value": 860000,
          "currency": "BRL"
        },
        "payment_method": {
          "type": "CREDIT_CARD",
          "installments": 1,
          "capture": true,
          "card": {
            "number": "9999999999999999",
            "exp_month": "12",
            "exp_year": "2000",
            "security_code": "123",
            "holder": {
              "name": "Teste Split"
            }
          }
        },
        "splits": {
          "method": "PERCENTAGE",
          "receivers": [
            {
              "account": {
                "id": "ACCO_99999999-9999-9999-9999-999999999999"
              },
              "amount": {
                "value": 10
              },
              "reason": "Receiver 1",
              "configurations": {
                "custody": {
                  "apply": true,
                  "release": {
                    "scheduled": "2025-09-17T12:14:49.216-03:00"
                  }
                }
              }
            },
            {
              "account": {
                "id": "ACCO_00000000-0000-0000-0000-000000000000"
              },
              "amount": {
                "value": 90
              },
              "reason": "Receiver 2",
              "configurations": {
                "custody": {
                  "apply": false
                }
              }
            }
          ]
        },
        "notification_urls": [
          "https://webhook.site/1904a76e-0024-4f16-a8d6-57ea49aa3fc4"
        ],
        "metadata": {
          "Exemplo": "Aceita qualquer informação"
        }
      }
    ]
  }'

Status do pedido

A custódia pode ter dois status principais:

HELD:Após a autorização de uma transação, esse status é informado. O saldo é bloqueado e não será liquidado até que atinja:
- a data de liberação automática informada no campo scheduled, ou
- seja liberado manualmente via API.
  Enquanto o valor estiver bloqueado, o campo released_at permanecerá como null.
RELEASED: Esse status ocorre quando um pagamento tem seu valor desbloqueado. Para liberar uma custódia, você deve realizar a liberação via API, utilizando o endpoint Liberação Split com Custódia. Quando a liberação ocorre, o campo released_at será sempre preenchido com a data correspondente, seja ela anterior ou igual à data informada no campo scheduled.

📘
Se a liberação for feita antes da liquidação da transação, o valor permanecerá no saldo futuro e não será mais bloqueado na liquidação.

Para obter os dados mais recentes do pedido, utilize o endpoint Consultar divisão do pagamento, informando o ID (split_id) recebido no momento da criação do pedido com o endpoint Criar pedido. Abaixo é apresentado um exemplo de resposta ao endpoint Consultar divisão do pagamento. Note que o status da custódia e a data informada para liberação estão presentes em todos os objetos de receivers.

{
  "id": "SPLI_12345678-1234-1234-1234-123456789123",
  "method": "PERCENTAGE",
  "receivers": [
    {
      "payment": {
        "id": "12345678-1234-1234-1234-123456123456"
      },
      "account": {
        "id": "ACCO_99999999-9999-9999-9999-999999999999"
      },
      "amount": {
        "value": 10.0,
        "refunded": 0
      },
      "configurations": {
        "custody": {
          "apply": true,
          "release": {
            "scheduled": "2025-09-17T12:14:49.216-03:00",
            "released_at": "2025-06-26T11:04:10.365-03:00"
          },
          "status": "RELEASED"
        },
        "chargeback": {
          "charge_transfer": {
            "percentage": 0.0
          }
        },
        "liable": true,
        "statement": {
          "amount": {
            "show_full_value": true
          }
        }
      },
      "reason": "Receiver 1",
      "type": "PRIMARY"
    },
    {
      "payment": {
        "id": "87654321-1234-1234-1234-123456123456"
      },
      "account": {
        "id": "ACCO_00000000-0000-0000-0000-000000000000"
      },
      "amount": {
        "value": 90.0,
        "refunded": 0
      },
      "configurations": {
        "custody": {
          "apply": false,
          "release": {
            "scheduled": null
          }
        },
        "chargeback": {
          "charge_transfer": {
            "percentage": 0.0
          }
        },
        "liable": false,
        "statement": {
          "amount": {
            "show_full_value": false
          }
        }
      },
      "reason": "Receiver 2",
      "type": "SECONDARY"
    }
  ],
  "links": [
    {
      "rel": "SELF",
      "href": "https://sandbox.api.pagseguro.com/splits/SPLI_12345678-1234-1234-1234-123456789123",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "ORDER",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_12345678-1234-1234-1234-123456789876",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "CHARGE",
      "href": "https://sandbox.api.pagseguro.com/charges/CHAR_12345678-1234-1234-1234-123456123456",
      "media": "application/json",
      "type": "GET"
    }
  ]
}

Liberação do pagamento

Para liberar o valor associado a um pagamento com custódia, use o endpoint Liberar divisão de pagamento com custódia.

📘
Apenas o usuário dono da transação pode realizar a liberação da custódia. Se um usuário que não for o dono tentar realizar a liberação, um erro será gerado.

Benefícios da custódia

📘Informações básicas sobre divisão de pagamento

Processo de criação do pedido

Regras de utilização

Criando o pedido

Status do pedido

📘

Liberação do pagamento

📘

📘
Informações básicas sobre divisão de pagamento