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:
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 90 dias. Após esse prazo, a transação será liberada automaticamente.
- Liberação: Para liberar uma transação com custódia, utilize o 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.
Você deve adicionar a indicação de uso de custódia para todos os recebedores, ou seja, todos os objetos dentro do array receivers devem conter configurations.custody.apply = true. Se essa informação não estiver presente em para todos os recebedores, um erro será gerado. O exemplo abaixo apresenta a configuração do objeto split de uma operação com dois recebedores. Note como o objeto configuration se repete.
"splits": {
"method": "PERCENTAGE",
"receivers": [
{
"account": {
"id": "ACCO_12345-8A06-4B3F-9AC1-40C3AB77B16D"
},
"amount": {
"value": 90
},
"configurations": {
"custody": {
apply: true
}
}
},
{
"account": {
"id": "ACCO_12345-C53C-40FD-80B1-5FD10F17794A"
},
"amount": {
"value": 10
},
"configurations": {
"custody": {
apply: true
}
}
}
]
},
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 --request POST 'https://sandbox.api.pagseguro.com/orders' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '
{
"reference_id": "referencia do pedido",
"customer": {
"name": "Jose da Silva",
"email": "[email protected]",
"tax_id": "12345678909",
"phones": [
{
"country": "55",
"area": "11",
"number": "999999999",
"type": "MOBILE"
}
]
},
"items": [
{
"reference_id": "referencia do item",
"name": "nome do item",
"quantity": 1,
"unit_amount": 10000
}
],
"shipping": {
"address": {
"street": "Avenida Brigadeiro Faria Lima",
"number": "1384",
"complement": "apto 12",
"locality": "Pinheiros",
"city": "São Paulo",
"region_code": "SP",
"country": "BRA",
"postal_code": "01452002"
}
},
"notification_urls": [
"https://meusite.com/notificacoes"
],
"charges": [
{
"reference_id": "referencia do pagamento",
"description": "descricao do pagamento",
"amount": {
"value": 10000,
"currency": "BRL"
},
"splits": {
"method": "PERCENTAGE",
"receivers": [
{
"account": {
"id": "ACCO_12345-8A06-4B3F-9AC1-40C3AB77B16D"
},
"amount": {
"value": 90
},
"configurations": {
"custody": {
apply: true
}
}
},
{
"account": {
"id": "ACCO_12345-C53C-40FD-80B1-5FD10F17794A"
},
"amount": {
"value": 10
},
"configurations": {
"custody": {
apply: true
}
}
}
]
},
"payment_method": {
"type": "CREDIT_CARD",
"installments": 1,
"capture": true,
"card": {
"number": "4111111111111111",
"exp_month": "12",
"exp_year": "2026",
"security_code": "123",
"holder": {
"name": "Jose da Silva",
"tax_id": "65544332211"
},
"store": false
}
},
}
]
}'
Status do pedido
A custódia pode ter dois status principais:
- HELD: Após a liquidação de uma transação com custódia, esse status é informado. O valor deixa de fazer parte do saldo futuro e é enviado para o saldo bloqueado.
- RELEASED: Esse status ocorre quando um pagamento tem seu valor desbloqueado. Para que uma custódia seja liberada, o você deve realizar a liberação via API, utilizando o endpoint [Liberação Split com Custódia].
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, você deve utilizar o endpoint Consultar divisão do pagamento informando o ID (split_Id) recebido no memento 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 está presente em todos os objetos de receivers.
{
"id":"SPLI_XYZ-6B28-442C-AB1C-4A346E5EBF74",
"method":"FIXED",
"receivers":[
{
"payment":{
"id":"000012329-FF42-4E02-8E7C-0B9FC9D50838"
},
"account":{
"id":"ACCO_1234-EC68-4208-8553-E016DF30CA81"
},
"amount":{
"value":32000,
"refunded":0
},
"configurations":{
"custody":{
"apply":true,
"status":"HELD"
},
"chargeback":{
"charge_transfer":{
"percentage":null
}
},
"liable":true,
"statement":{
"amount":{
"show_full_value":true
},
"items":[
]
}
},
"reason":"Receiver 1",
"type":"PRIMARY"
},
{
"payment":{
"id":"ABC123-5436-4018-ABF7-05A1A0CA9645"
},
"account":{
"id":"ACCO_12344-13D0-4903-8AFC-1AAC3CAE73C3"
},
"amount":{
"value":8000,
"refunded":0
},
"configurations":{
"custody":{
"apply":true,
"status":"HELD"
},
"chargeback":{
"charge_transfer":{
"percentage":null
}
},
"liable":false,
"statement":{
"amount":{
"show_full_value":false
},
"items":[
]
}
},
"reason":"Receiver 2",
"type":"SECONDARY"
}
]
}
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.