Processando pagamentos

Sobre este guia#

Neste guia vamos descrever o passo-a-passo para que você processe pagamentos com o PicPay através de nossa solução de pagamentos logada.

Antes de começar#

Antes de processar pagamentos online através de nossa solução de PicPay 1-Click, você deve possuir um access_token válido e não expirado. Você pode conferir como gerar seus tokens neste artigo.

Como funciona#

Autenticação#

Para esta operação, apenas o access_token, gerado dinamicamente, é necessário.

Gerando uma cobrança na carteira do usuário#

Possuindo um access_token válido, o processo de geração de uma cobrança na carteira dos clientes é extremamente simples e fluido. A cobrança deverá ser gerada através do end-point v1/payments/charge, indicando o valor a ser debitado no corpo da requisição. No exemplo abaixo, estamos solicitando a cobrança de R$ 3,00 na carteira do usuário.

curl  --location --request POST 'https://api.picpay.com/v1/payments/charge' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--header 'x-Idempotency-Key: {{idempotency_key}}' \
--data '{
    "value": 0.1,
    "reference_id": "c413fcb5-d963-4b93-8218-3b776f656553",
    "auto_capture": true,
    "description": "{DESCRICAO_PRODUTO}",
    "transaction_initiator": "{ENUM_INITIATOR}" 
}'

info

Campo description: se refere ao descritivo da compra. Este campo é parametrizável, sendo necessário alinhamento prévio com o negócio.

info

Campo transaction_initiator: Indica quem iniciou o fluxo da transação.
Este campo é opcional e, quando informado, deve ser um dos valores do ENUM abaixo:

MIT — O vendedor (seller) iniciou o fluxo da transação (ex: recorrência).
CIT — O consumidor (consumer) iniciou o fluxo da transação.

Caso não informado, o campo será nulo.
Importante: Este campo não é retornado nos responses das chamadas ao endpoint charge, mesmo que seja enviado no request.
Seu uso é restrito a controle interno dos fluxos de pagamento.

Abaixo um exemplo de retorno de sucesso. Os campos transaction_id e reference_id devem ser guardados pois são as chaves para processos de estorno.

{
    "transaction_id": "e646263b-2b4d-4b2c-93d8-2568fbffb744",
    "reference_id": "04c923a4-34d6-43e8-89db-1b563f887b53",
    "created_at": "2021-02-22 19:29:16"
}

Qual será a origem dos fundos ?#

O valor da cobrança poderá ser debitado do cartão de crédito, saldo ou ambos (saldo + cartão). Caso o cliente possua a opção de Usar saldo habilitada no App, iremos consumir primeiramente o saldo do usuário e posteriormente (caso não haja saldo suficiente), efetuar uma cobrança no cartão.

Exemplo: Estou efetuando uma compra de R$60, possuo R$19 de saldo em minha carteira. O PicPay irá consumir os R$19 e efetuar uma cobrança de R$41 no cartão cadastrado.

Mensagens de erro#

Não informamos os códigos de erro nos retornos das transações. Apenas informamos se a transação foi aprovada ou não.

{
    "message":"Unauthorized transaction."
}

Timeout de cobrança#

Atualmente um pagamento tem como timeout padrão o valor de 30 segundos. Esse gerenciamento é feito internamente para evitar problemas com cobranças indevidas. Na prática, caso o pagamento demore mais de 30 segundos para retornar um sucesso, a API retornará um erro 500. Se o pagamento for resolvido posteriormente, ele será automaticamente desfeito por meio de um reembolso automático.

Se a API da sua aplicação tiver um timeout diferente do padrão de 30 segundos, será necessário atualizar essa configuração diretamente no Painel do Lojista no PicPay. Confira o passo a passo para realizar essa atualização.

Nesses casos a requisição responderá com o HTTP Status Code 408 Request Timeout e com o seguinte body:

{
    "message": "Request took too long to process.",
    "business_code": "REQUEST_TIMEOUT"
}

Próximos passos#

Obtendo ajuda#

Esperamos ter ajudado com este artigo! Caso tenha restado alguma dúvida, você pode consultar o nosso FAQ ou entrar em contato através do e-mail negocios@atendimento.picpay.com.