API Reference

PIX - Cash In

Este endpoint permite a criação de uma requisição de cash in PIX

Endpoint de Referência

  • POST /accounts/pix/cashin

Este endpoint permite você criar transações de cash-in. Oferecemos algumas variações de interesse para os parceiros:

  1. Request Completa: envolve fornecer todos os dados, tornando-os obrigatórios, como o solicitante e o valor.
  2. Pagador Anônimo: permite omitir o os dados do solicitante, desta forma, qualquer pagador será aceito para a transação.
  3. Valor Editável: permite configurar se o valor a ser pago pode ser definido pelo usuário final, ou se precisa ser pago exclusivamente o valor definido.

Cenários de Sucesso

Cenário 1: Request Completa

O payload da request é composto por três objetos internos: payment, transaction e webhook, conforme visto neste exemplo de payload de request.

{
  "payment": {
    "payer": {
      "name": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "value": {
      "original": "50",
      "editable": false      
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Os Campos da Request
CampoTipoRequiredDescrição
payment.payerobjectfalseO CPF do usuário final (requisitante). Atenção à observação sobre pagador anônimo, ao final da seção
payment.payer.cpfstringfalseSe o objeto payer é fornecido, trata-se do CPF do usuário final (requisitante).
payment.payer.namestringfalseSe o objeto payer é fornecido, trata-se do nome do usuário final (requisitante).
paymentobjecttrueUm objeto que define os dados de pagamento.
payment.value.originalstringtrueO valor efetivo a ser pago.
payment.value.editablebooleanfalseEsta flag especifica se o usuário final pode pagar um valor diferente do original especificado. Se não fornecido, a configuração padrão é false, ou seja, o valor a ser pago deve ser igual ao definido no campo original. Atenção à observação sobre valor editável, ao final da seção
transaction.orderIdstringtrueUma orderId customizada fornecida pelo integrador, para idempotência e caso queira fazer uma contraverificação quando a resposta é recebida.
transaction.orderDescriptionstringfalseUma descrição customizada fornecida pelo integrador, caso queira fazer uma contraverificação quando a resposta é recebida.
webhook.urlstringtrueUma URL absoluta para receber eventos de notificação webhook.
webhook.customHeaderNamestringfalseUm nome de cabeçalho personalizado para contraverificação quando a mensagem do webhook é recebida.
webhook.customHeaderValuestringfalseUm valor associado ao cabeçalho para contraverificação quando a mensagem de webhook é recebida.
  • Resposta de Sucesso (201 - Created)
{
    "statusCode": "Done",
    "data": {
        "transaction": {
            "id": "625a913f-ac58-499a-8f91-4917aa8fedda",
            "orderId": "in-1414870875-158709817091784",
            "date": "2023-10-27T01:59:01.023Z",
            "state": "Registered",
            "amount": "50"
        },
        "payment": {
            "qrCode": "77914780075295699696br.gov.bcb.pix2564qrcode.sandbox.paybrokers.solutions/QR/cob/488968451850629566092063417102430176450477573197289273442834PayBrokers Cobrança e Serviço em Tecnologia Ltda10484911785727998087***1DFA8C33",
            "qrCodeLocation": "https://api.sandbox.paybrokers.solutions/v1/system/qrcodeviewer/625a913f-ac58-499a-8f91-4917aa8fedda"
        }
    }
}
  • Os Campos da Resposta
CampoTipoDescrição
transaction.idStringUm identificador exclusivo (UID)
transaction.orderIdStringUm ID opcional fornecido pelo integrador na solicitação de transação para contraverificação
transaction.dateStringA data de criação do pedido de transação
transaction.stateStringO estado inicial da transação. Ele começa como Registered, o que significa que já está cadastrado em um banco e está aguardando o pagamento.
transaction.amountStringO valor da transação. Um número em formato flutuante com até 6 dígitos decimais, como 15,000000
payment.qrCodeStringUm código feito sob medida para o recurso PIX Copia e Cola nos aplicativos do banco, facilitando a execução do pagamento sem problemas.
payment.qrCodeLocationStringA URL de um QR Code gráfico a ser escaneado nos aplicativos do banco PIX, possibilitando o início do pagamento

📘

Validação de CPF

O PayBrokers valida o CPF e nega pedidos de CPFs falsos. Para testar, procure e utilize um CPF do mundo real. Caso tenha dificuldades, procure o suporte técnico.

Cenário 2: Pagador anônimo e Valor Não Editável

{
  "payment": {
    "value": {
      "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Resposta de Sucesso (201 - Created)
{  
  "statusCode": "Done",  
  "data": {  
    "transaction": {  
      "id": "69159007-1c5f-4cfa-b6cc-cc36aac14f85",  
      "orderId": "in-1414870875-158709817091784",  
      "date": "2023-07-19T03:37:24.710Z",  
      "state": "Registered",  
      "amount": "50"  
    },  
  }  
}

Cenário 3: Pagador Anônimo e Valor Editável

{
  "payment": {
    "value": {
      "original": "50",
      "editable": true      
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Resposta de Sucesso (201 - Created)
{
    "statusCode": "Done",
    "data": {
        "transaction": {
            "id": "9947b80a-8107-4264-938d-56a7f43593f5",
            "orderId": "in-1414870875-158709817091784",
            "date": "2023-10-27T01:58:14.573Z",
            "state": "Registered",
            "amount": "50"
        },
        "payment": {
            "qrCode": "76616684937466847221br.gov.bcb.pix2564qrcode.sandbox.paybrokers.solutions/QR/cob/504920436013785957047772193456164644706748877985089166204308PayBrokers Cobrança e Serviço em Tecnologia Ltda78445932284303602542***BA5BD701",
            "qrCodeLocation": "https://api.sandbox.paybrokers.solutions/v1/system/qrcodeviewer/9947b80a-8107-4264-938d-56a7f43593f5"
        }
    }
}

🚧

Sobre as Pagador Anônimo

É responsabilidade do integrador atualizar a informação do efetivo pagador da transação, recebida através de evento do Webhook, após o efetivo pagamento.

🚧

Sobre o Valor Editável

É responsabilidade do integrador garantir que o valor recebido através de evento do Webhook, após o efetivo pagamento da transação, será o valor considerado em sua plataforma.

Cenários de Falha (Exemplos Úteis)

Cenário 1: Campo requerido vazio (payment.payer)

{
  "payment": {
    "payer": {
    },
    "value": {
      "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Resposta de Falha (400 - Bad Request)
{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment/payer",
        "code": "required",
        "message": "must have required property 'cpf'",
        "info": {
          "missingProperty": "cpf"
        }
      }
    ]
  }
}

Cenário 2: Falha de Autenticação

Se uma solicitação incluir um token de autenticação expirado ou inválido, o seguinte erro será retornado.

  • Resposta de Falha (401 Unauthorized)
{
  "statusCode": "Error",
  "error": {
    "name": "AuthenticationError",
    "message": "The authorization token is invalid",
    "details": {
      "reason": "AuthenticationTokenInvalid"
    }
  }
}

Cenário 3: Dado de entrada inválido payment.payer.cpf.

{
  "payment": {
    "payer": {
	    "cpf": "50194184190"
    },
    "value": {
	    "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Resposta de Falha(409 - Conflict)
{
  "statusCode": "Error",
  "error": {
    "name": "OperationError",
    "code": "OperationError",
    "details": {
      "reason": "CounterpartyTaxNumberInvalid",
      "message": "TaxNumber:50194184190"
    }
  }
}

❗️

Requests Malformadas

Durante os testes, é possível que os integradores forneçam alguma requisição incompleta ou malformada que gere como resposta um erro 500 - Internal Server Error.