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 endpoint 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.

Endpoint#

POST https://ecommerce-api.svc.picpay.com/v1/payments/charge

Exemplo de requisição#

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

Parâmetros do body#

Campo	Tipo	Obrigatório	Descrição
`value`	`float`	Sim	Valor da cobrança (máx. 5 inteiros, 2 decimais)
`reference_id`	`string`	Não	Identificador externo do seller
`auto_capture`	`boolean`	Não	Default: `true`. Se `false`, habilita captura tardia
`description`	`string`	Não	Descritivo da compra (máx. 256 caracteres)
`transaction_initiator`	`enum`	Não	`MIT` (seller iniciou) ou `CIT` (consumer iniciou)

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.

Status resultantes#

Status	Cenário
`PAID`	Aprovada com captura automática
`AUTHORIZED`	Aprovada com captura tardia (`auto_capture: false`)
`REFUSED`	Recusada (qualquer motivo)
`ERROR`	Timeout (>30s) — transação desfeita automaticamente

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, captura e consulta.

{
    "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#

`business_code`	HTTP	Descrição
`INSUFFICIENT_FUNDS`	200	Saldo insuficiente. O usuário deve adicionar fundos ou cadastrar cartão
`INVALID_FUNDING_SOURCE`	422	Cartão inválido. Não tentar novamente
`FUNDING_SOURCE_UNAVAILABLE`	422	Meio de pagamento indisponível
`RISK_DECLINED`	422	Recusada por análise de risco
`ACCOUNT_CLOSED`	422	Conta encerrada
`ACCOUNT_ON_HOLD`	422	Conta temporariamente bloqueada
`TRANSACTION_EXCEEDS_LIMIT`	422	Excede limite da conta
`TRANSACTION_EXCEEDS_MONTHLY_LIMIT`	422	Excede limite mensal
`TRANSACTION_ENRICHMENT_BAD_REQUEST`	422	Configuração de produto/perfil incorreta
`USER_RETRIES_EXCEEDED`	422	Excedidas tentativas permitidas
`DUPLICATED_TRANSACTION`	409	Transação duplicada
`DUPLICATED_REFERENCE_ID`	409	`reference_id` duplicado para o seller
`REQUEST_TIMEOUT`	502	Timeout (>30s). Transação desfeita automaticamente
`PSP_PAYMENT_ERROR`	502	Erro no provedor de pagamento
`SERVICE_UNAVAILABLE`	502	Serviço temporariamente indisponível

Para recusas de cartão, o response inclui acquirer_response com reason_code e reason_message por bandeira (ABECS 021).

Timeout de cobrança#

Atualmente um pagamento tem como timeout padrão o valor de 30 segundos. Caso o pagamento demore mais de 30 segundos, a API retornará HTTP 502 com business_code: REQUEST_TIMEOUT. Se o pagamento for resolvido posteriormente, será automaticamente desfeito por meio de um reembolso automático.

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