Pular para o conteúdo principal

P2P em Lote

Permite que um marketplace/Manager envie várias transferências P2P internas (sem PIX/SPB) em uma única chamada, via upload de arquivo CSV. O processamento de cada transferência é assíncrono: o lote é aceito imediatamente e cada transferência pode ser acompanhada individualmente por identificador, com o desfecho notificado via callback HTTP (não via polling).

Visão geral da arquitetura​

  • gateway-payment: recebe o lote via CSV, persiste os dados (batches → chunks → transactions, com method="P2P") e repassa as transferências para processamento assíncrono.
  • O desfecho de cada transferência (PAID ou ERROR) é recebido via callback interno e refletido no status consultável pelo cliente.

Enviar lote​

MétodoPOST
Path/api/p2p/batch
AutenticaçãoAuthorization (******

Autenticação​

Exige o header Authorization com um token válido e não expirado, emitido previamente para o integrador. Se ausente, mal formatado, ou o token for inválido/expirado, a API retorna 401 Unauthorized:

{ "error": "Token ausente ou inválido" }

ou

{ "error": "Token inválido" }

Corpo da requisição​

multipart/form-data, com o arquivo CSV no campo file.

Formato do CSV (id,sender_channel_id,receiver_channel_id,value,description):

id,sender_channel_id,receiver_channel_id,value,description
1,8c0a1e4a-1111-4a7a-9c2b-000000000001,8c0a1e4a-2222-4a7a-9c2b-000000000002,15000,Pagamento pedido #1001
2,8c0a1e4a-1111-4a7a-9c2b-000000000001,8c0a1e4a-3333-4a7a-9c2b-000000000003,2500,Pagamento pedido #1002
CampoTipoObrigatórioDescrição
idstringSimIdentificador único da transferência dentro do lote, usado como external_id para idempotência
sender_channel_iduuidSimCanal de origem dos fundos
receiver_channel_iduuidSimCanal de destino dos fundos
valueintegerSimValor da transferência em centavos (ex.: 15000 = R$ 150,00). Deve ser maior que zero
descriptionstringNãoDescrição/memo da transferência

Exemplo de requisição:

POST /api/p2p/batch HTTP/1.1
Host: gateway-payment.internal
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: multipart/form-data; boundary=----boundary

------boundary
Content-Disposition: form-data; name="file"; filename="lote.csv"
Content-Type: text/csv

id,sender_channel_id,receiver_channel_id,value,description
1,8c0a1e4a-1111-4a7a-9c2b-000000000001,8c0a1e4a-2222-4a7a-9c2b-000000000002,15000,Pagamento pedido #1001
------boundary--

Respostas​

202 Accepted — lote aceito para processamento assíncrono:

{
"batch_id": "f1e2d3c4-b5a6-4789-9abc-def012345678",
"transfer_ids": [
"11111111-aaaa-4b11-9c11-111111111111",
"22222222-bbbb-4b22-9c22-222222222222"
],
"received_count": 2
}

400 Bad Request — CSV malformado, campo obrigatório ausente ou value <= 0:

{ "message": "Arquivo CSV inválido" }
{ "message": "Todos os campos são obrigatórios" }
{ "message": "O valor deve ser maior que zero" }

Idempotência​

Reenviar o mesmo lote (mesmos ids de linha) não duplica transferências: a validação é feita a partir do external_id (campo id do CSV) associado à transaction já existente.