Picpay é uma solução que permite a realização de pagamentos online através do saldo disponível na carteira do aplicativo.

​
Os participantes de uma transação Picpay

  • O recebedor, cliente da Malga que deve possuir uma conta ativa da Picpay Negócios.
  • O pagador, um comprador que é um cliente Picpay.

​
Fluxo de pagamento Picpay

  • Para criar uma transação com picpay basta informar o meio de pagamento picpay na criação de uma cobrança, e os documentos que identifiquem o comprador;
  • Uma cobrança é registrada diretamente no sistema da Picpay;
  • O pagador deve realizar o pagamento da cobrança diretamente em seu aplicativo Picpay, através do qrcode ou código copia e cola, retornados pela picpay;
  • Após confirmação do pagamento, a Picpay enviará uma notificação para a Malga informando que o pagamento foi realizado;
  • Posteriormente o Cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso.
Este processo está descrito no diagrama a seguir. Fluxo Picpay
As cobranças Picpay são assíncronas por natureza, ou seja, ao criar uma nova cobrança você terá a confirmação apenas da criação da cobrança e não de sua conclusão. A autorização ou reprovação de uma cobrança é notificada através dos webhooks.

​
Notificação de alteração de status

objetoeventodescrição
transactionpendingEvento enviado quando a cobrança é registrada e a notificação de cobrança foi enviada para o pagador
transactionauthorizedEvento enviado quando é reconhecida a confirmação do pagamento da cobrança
transactionfailedEvento enviado quando a cobrança não é criada com sucesso, sem estorno financeiro
transactioncanceledEvento enviado quando a cobrança é negada pela Picpay antes de ter sido autorizada, sem estorno financeiro
transactionvoidedEvento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro

​
Testando recebimento de notificação de cobrança Picpay paga

Para testar sua integração com os webhooks da Malga você pode desenvolver direto seu sistema ou utilizar algum serviço como request.bin ou pipedream.com para validar inicialmente os eventos enviados. Basta gerar um novo endpoint nestes serviços e cadastrar um webhook na Malga com o endpoint gerado que todos os eventos enviados ficarão registrados nestes serviços para consulta e debug. Permitimos no ambiente de sandbox sandbox-api.malga.io a atualização manual de transações criadas para os status de authorized, voided e charged_back, dessa forma você consegue criar uma transação e simular o evento desejado. Requisição para atualizar manualmente uma cobrança Picpay como paga em sandbox 
curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/<CHARGE_ID>' \
          --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
          --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "status": "authorized"
          }'

​
Exemplo de cobrança

Realize uma cobrança Picpay a partir dos dados do comprador usando o Serviço de Charges. 
curl --location --request POST 'https://api.malga.io/v1/charges' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "d5b792ba-4d76-46b4-a94d-c7ddae75cf9e",
    "orderId": "5556",
    "amount": 100,
    "currency": "BRL",
    "paymentMethod": {
        "paymentType": "picpay",
    },
    "paymentSource": {
        "sourceType": "customer",
        "customer": {
            "document": {
                "number": "36436702067",
                "type": "cpf"
            },
            "name": "Jose das Flores",
            "email": "jose@gmail.com",
            "phoneNumber": "11998324141",
            "address": {
                "street": "Rua 1",
                "streetNumber": "120",
                "zipCode": "01714140",
                "state": "SP",
                "city": "São Paulo"
            }
        }
    },
    "fraudAnalysis": {
        "customer": {
            "browser": {
                "ipAddress": "127.0.0.1"
            }
        },
        "cart": {
            "items": [
                {
                    "sku": "123",
                    "name": "desc",
                    "quantity": 1,
                    "unitPrice": 1,
                    "risk": "Low"
                }
            ]
        }
    }
}'

< HTTP/2 201
{
    "id": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1",
    "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d",
    "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176",
    "description": null,
    "orderId": "8222",
    "createdAt": "2024-08-10T21:33:42.955Z",
    "amount": 100,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": null,
    "status": "pending",
    "paymentMethod": {
        "paymentType": "picpay",
        "qrCodeData": "00020101021226860014COM.PICPAY.P2B0164https://app.picpay.com/checkout/NjY4YmZhNjA5OTdhNTU2YTNmMGRmZTIy5204000053039865802BR5906PICPAY6009SAO PAULO62280524668bfa60997a556a3f0dfe2280580020COM.PICPAY.ECOMMERCE0107nc=true0219checkout=stepbystep6304B9EE",
        "qrCodeImageUrl": "https://...."
        "expiresIn": 1722971550
    },
    "paymentSource": {
        "sourceType": "customer",
        "customerId": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f"
    },
    "transactionRequests": [
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2024-08-10T21:33:42.969Z",
            "updatedAt": "2024-08-10T21:33:44.105Z",
            "idempotencyKey": "2c57caad-136d-4bc4-a265-c72d408d5ef8",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "43a107b3",
            "transactionId": "2c57caad-136d-4bc4-a265-c72d408d5ef8",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "pending",
            "requestStatusReason": null,
            "responseTs": "778ms"
        }
    ]
}

​
Estorno Picpay

O estorno Picpay, assim como a cobrança, acontece de forma assíncrona. Isto significa que uma vez solicitado é iniciado o processo de estorno, que terá seu prazo máximo para finalização determinado na propriedade delayToCompose, em dias. O fluxo de um estorno está representado no diagrama a seguir. Fluxo de Estorno Picpay

​
Exemplo de solicitação de estorno Picpay

Quando uma solicitação de estorno é feita, é recebida de volta uma transação com status refund_pending e uma transactionRequest do tipo void com status processing informando que o estorno está sendo processado. 
curl --location --request POST 'https://api.malga.io/v1/charges/<CHARGE_ID>/void' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 100,
    "delayToCompose": 100
}'

< HTTP/2 201
{
    "id": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1",
    "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d",
    "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176",
    "description": null,
    "orderId": "8222",
    "createdAt": "2022-09-30T21:33:42.955Z",
    "amount": 100,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": null,
    "status": "refund_pending",
    "paymentMethod": {
        "paymentType": "picpay"
        "qrCodeData": "00020101021226860014COM.PICPAY.P2B0164https://app.picpay.com/checkout/NjY4YmZhNjA5OTdhNTU2YTNmMGRmZTIy5204000053039865802BR5906PICPAY6009SAO PAULO62280524668bfa60997a556a3f0dfe2280580020COM.PICPAY.ECOMMERCE0107nc=true0219checkout=stepbystep6304B9EE",
        "qrCodeImageUrl": "https://...."
        "expiresIn": 1722971550
    },
    "paymentSource": {
        "sourceType": "customer",
        "customerId": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f"
    },
    "transactionRequests": [
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "PICPAY",
            "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "processing",
            "requestType": "void",
            "responseTs": "1123ms"
        },
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "PICPAY",
            "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": null
        },
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "PICPAY",
            "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "pending",
            "responseTs": "1084ms"
        }
    ]
}

​
Testando atualização de estorno

Ao criar um estorno para uma transação Picpay em nosso sandbox, o mesmo será criado com o status refund_pending. Para testar uma atualização de estorno no sandbox da Malga você deve atualizar manualmente a transação com uma requisição, conforme descrito na sessão de recebimento de notificações. Requisição para atualizar manualmente uma cobrança Picpay como estornada em sandbox 
curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/<CHARGE_ID>' \
          --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
          --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "status": "voided"
          }'