Pix

Pix is the Brazilian instant payment. The payment method created by the Central Bank (BC) in which funds are transferred between accounts in a few seconds, any time or day. It is practical, fast and secure. Pix can be made from a checking account, savings account or prepaid payment account.

Pix is designed to be a very broad payment method. Any payment or transfer that is made nowadays using different means (TED - electronic transfer of funds, card, invoice/payment slips, etc.) can be made with Pix, simply by using a cell phone.

Malga performs the role of a payment intermediary, but does not perform the financial clearance, therefore it is necessary to have an account in a financial institution that is part of the instant payment system. Thus, we receive the data sent by the customer in the charges’ API and communicate with issuers and fintechs.

The Pix participants:

The payee, Malga's customer who must have an account at a partner financial institution to receive payments via Pix
The payment provider, a financial institution where the customer has an account, responsible for issuing a dynamic QR Code with the payee's bank details and the data of the product offered.
The payer, a buyer of any kind who must scan the dynamic QR Code in the application of the financial institution of his choice to make the payment.

Pix payment flow:

To create a transaction with Pix the customer simply informs the Pix payment method when creating a charge, its expiration date and data that identifies the buyer;
A charge is registered in the central bank's instant payment system and becomes available for payment and the QR Code data is returned in the format of an image, which can be scanned by the payer, and a code, which can be copied by the payer;
The Customer must present the data related to the charge (QRcode image or copy and paste code) to the payer who must make the payment within the expiration period defined in the bill by the payee;
The payer must pay the QR Code at the financial institution of his choice;
After confirmation of the payment, the payment provider will perform the transfer of funds via the new instant payment system to the payee's account.
Subsequently the payee customer will be notified that the payment has been made and the charges were successfully completed.

Payment flow associated with the customer

Create a customer;
Create a new charge providing the previously created customer as the paymentSource, thus using the buyer's data for generating the charge.

Pix refund

It is possible to carry out partial refund or full refund for Pix type payments.
To carry out the refund of transactions with Pix, it is necessary to send a request for a billing void informing the id of the transaction that must be refunded.

Supported providers for charges via Pix:

ProviderType	Description
`BS2`	Bank BS2 Business
`BB`	Banco do Brasil Individual
`PAGARME`	Pagar.me
`MERCADO_PAGO`	Mercado Pago
`ZOOP`	Zoop
`PAGSEGURO`	PagSeguro
`ADYEN`	Adyen
`GETNET`	Getnet
`NUPAY`	Nupay
`SANDBOX`	Simulator used to authorize payments in an sandbox environment

tip

The Pix method of payment when created on Malga is registered with a pending status, being automatically updated to authorized status when we are notified by the financial institution of the payment confirmation, this time may vary from provider to provider, and cannot exceed the expiration time defined in the creation of the charge.

Change of Status Notification

objeto	evento	descrição
transaction	pending	Event sent when the charge is registered and payment data is available
transaction	authorized	Event sent when the payment confirmation of the charges is recognized
transaction	failed	Event sent when the charges are denied by the financial institution before it has been authorized, without financial refund
transaction	refund_pending	Event sent when a refund is requested and it is still processing
transaction	voided	Event sent when Malga receives confirmation of total or partial Pix refund

caution

It is possible that the paid value from a Pix transaction with authorized status is different from it's original intended amount, due to fees and discounts for instance. Always check the value returned in the amount field from the transactions to identify the correct paid amount.

Refunds

It is possible to totally and partially refund Pix charges, depending on the financial institution being used. For partial refunds, you must request a refund with an amount smaller than the total amount of that charge, the payer will be reembursed for partial amount and the charge will remais as authorized with the remaining amount available for clearance.

To request a partial refund you must make a void request sending an amount smaller than the transaction's original amount. The amount sent in such request will be refunded and the transaction will have it's own amount updated to reflect the reduction from the partial refund.

caution

The originalAmount property from the charge object stays the same from when the transaction was authorized. It represents the original amount sent to create that transaction when it was first approved. The amount property, on the other hand, changes reflecting all refund actions processed.

It is important to point ou that it is possible to process multiple partial refunds within a single transaction as long as the sum of all refunded value does not exceed the original amount of that transaction. All historic refunds processed on a transaction can be verified in the transactionRequest node inside the charge object.

info

Transactions will remain authorized as long as there is some amount to be received by the payee and it transits to voided only when all the original amount of the transaction was refunded.

When a Pix refund is requested, a new transactionRequest will be created with a void requestType and a processing requestStatus. When the refund is completed a new transactionRequest will be created with a void requestType and success requestStatus.

Pix refund is asynchronous by nature. When a new refund request is created the transaction status transits to refund_pending and is automatically updated to voided when we're notified by the financial institution that the refund was completed.

Pix refund flow

Supported providers for Pix refund

ProviderType	Total refund	Partial refund
`MERCADO_PAGO`	X	X
`PAGARME`	X	X
`BB`	X	X
`BS2`
`ZOOP`	X	X
`PAGSEGURO`	X	X
`ADYEN`	X	X
`NUPAY`	X	X

Testing Pix webhook notifications

In order to test your integration with Malga's webhooks you can develop it straight into your systems or use a service such as request.bin or pipedream.com to initially validate the events being notificated. All you need to do is create a new endpoint in one of these services and register it as a Malga webhook and all events generated should be registered for further evaluation or debug.

In the sandbox environment, sandbox-api.malga.io, it is allowed to manually transit a transaction status to authorized, voided, refund_pending and charged_back. This way you can create a transaction and simulate the desired event.

Request to manually update a Pix as authorized in 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"
          }'

Example of billing via Pix

Perform a Pix charge using the buyer’s data through the Charges Service.

curl --location --request POST 'https://sandbox-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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
    "amount": 150,
    "currency": "BRL",
    "statementDescriptor": "Pedido #231 loja joão",
    "capture": true,
    "paymentMethod": {
      "paymentType": "pix",
      "expiresIn": 3600
    },
    "paymentSource": {
      "sourceType": "customer",
      "customer": {
        "name": "Jose Bonifacio Da Silveira",
        "phoneNumber": "21 98889999099",
        "email": "jose@gmail.com",
        "document": {
            "number": "72912053013",
            "type": "cpf"
        }
      }
    }
  }'

< HTTP/2 201
{
  "id": "148d5db0-f1c3-439f-902d-f1f268086e1d",
  "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
  "createdAt": "2012-06-30 23:59:59 +0000",
  "amount": 150,
  "originalAmount": 150,
  "currency": "BRL",
  "statementDescriptor": "Pedido #231 loja joão",
  "capture": true,
  "status": "pending",
  "paymentMethod": {
    "paymentType": "pix",
    "expiresIn": 3600,
    "qrCodeData": "00020101021126510014BR.GOV.BCB.PIX0129K89VdiUgWN1B3p0IHrgHkNHg9tX5F52040000530398654040.155802BR5913Customer test600062070503***630431C0",
    "qrCodeImageUrl": "https://...."
  },
  "paymentSource": {
    "sourceType": "customer",
    "customerId": "1cdcf0c9-eb04-4e43-b9b2-b7a4acdead1f"
  }
}

Example of refund via Pix

Perform a Pix refund sending the transaction id in the Refund Request.

curl --location --request POST 'https://sandbox-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": 150
}'

< HTTP/2 200
{
    "id": "1484a29e-4208-42cb-ba03-f9839b98690e",
    "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
    "clientId": "<YOUR_CLIENT_ID>",
    "description": null,
    "orderId": null,
    "createdAt": "2022-09-08T15:27:44.245Z",
    "amount": 150,
    "originalAmount": 150,
    "currency": "BRL",
    "statementDescriptor": "Pedido #231 loja joão",
    "capture": true,
    "status": "refund_pending",
    "paymentMethod": {
        "paymentType": "pix"
    },
    "paymentSource": {
        "sourceType": "customer",
        "customerId": "52a20b27-caae-4875-b455-a66f0fddcfc1"
    },
    "transactionRequests": [
        {
            "id": "4c379644-50b2-44e4-af03-62fbfaebc94a",
            "createdAt": "2022-09-08T15:29:26.950Z",
            "updatedAt": "2022-09-08T15:29:26.950Z",
            "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6",
            "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType": "MERCADO_PAGO",
            "transactionId": null,
            "amount": 150,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "processing",
            "requestType": "void",
            "responseTs": "713ms"
        },
        {
            "id": "8742b17c-47d6-464a-968e-e3f2a99eaffd",
            "createdAt": "2022-09-08T15:28:48.199Z",
            "updatedAt": "2022-09-08T15:28:48.199Z",
            "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6",
            "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType": null,
            "transactionId": null,
            "amount": 150,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": null,
            "pix": {
                "expiresIn": 3600,
                "qrCodeData": "00020101021126510014BR.GOV.BCB.PIX0129K89VdiUgWN1B3p0IHrgHkNHg9tX5F52040000530398654040.155802BR5913Customer test600062070503***630431C0",
                "qrCodeImageUrl": "https://...."
            }
        },
        {
            "id": "21fa762b-8634-4129-a25d-e8c8bdb64cb1",
            "createdAt": "2022-09-08T15:27:45.893Z",
            "updatedAt": "2022-09-08T15:27:52.406Z",
            "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6",
            "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType": "MERCADO_PAGO",
            "transactionId": "25593931617",
            "amount": 150,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "pending",
            "responseTs": "1356ms"
        }
    ]
}

Example of the refund webhook return

Webhook return when the refund request has it's status updated.

{
   "clientId":"<YOUR_CLIENT_ID>",
   "event":"transaction.voided",
   "payload":{
      "status":"voided",
      "id":"1484a29e-4208-42cb-ba03-f9839b98690e",
      "updatedAt":"2022-09-08T15:31:13.462Z",
      "createdAt":"2022-09-08T15:27:44.245Z",
      "idempotencyKey":null,
      "requestId":null,
      "orderId":null,
      "amount":150,
      "originalAmount":150,
      "currency":"BRL",
      "installments":null,
      "clientId":"<YOUR_CLIENT_ID>",
      "statementDescriptor":"Pedido #231 loja joão",
      "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
      "capture":true,
      "isProcessing":false,
      "customerId":null,
      "description":null,
      "fee":null,
      "feeAmount":null,
      "transactionRequests":[
         {
            "id":"21fa762b-8634-4129-a25d-e8c8bdb64cb1",
            "updatedAt":"2022-09-08T15:27:52.406Z",
            "createdAt":"2022-09-08T15:27:45.893Z",
            "idempotencyKey":"261fccac24c1412f9d23d5eab73418c6",
            "requestId":null,
            "providerId":"5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType":"MERCADO_PAGO",
            "networkTransactionId":"25593931617",
            "amount":150,
            "authorizationCode":null,
            "authorizationNsu":null,
            "requestStatus":"success",
            "requestType":"void",
            "responseTs":"1356ms",
            "pix":null,
            "boleto":null,
            "providerError":null,
            "providerAuthorization":null,
            "fraudAnalysis":null
         },
         {
            "id": "4c379644-50b2-44e4-af03-62fbfaebc94a",
            "createdAt": "2022-09-08T15:29:26.950Z",
            "updatedAt": "2022-09-08T15:29:26.950Z",
            "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6",
            "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType": "MERCADO_PAGO",
            "transactionId": null,
            "amount": 150,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "processing",
            "requestType": "void",
            "responseTs": "713ms"
         },
         {
            "id":"8742b17c-47d6-464a-968e-e3f2a99eaffd",
            "updatedAt":"2022-09-08T15:28:48.199Z",
            "createdAt":"2022-09-08T15:28:48.199Z",
            "idempotencyKey":"261fccac24c1412f9d23d5eab73418c6",
            "requestId":null,
            "providerId":"5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType":null,
            "networkTransactionId":null,
            "amount":150,
            "authorizationCode":null,
            "authorizationNsu":null,
            "requestStatus":"success",
            "requestType":"authorization",
            "responseTs":null,
            "pix":{
               "id":"71808df4-327f-493e-a046-48489b71e356",
               "updatedAt":"2022-09-08T15:28:48.199Z",
               "createdAt":"2022-09-08T15:27:49.543Z",
               "qrCodeData": "00020101021126510014BR.GOV.BCB.PIX0129K89VdiUgWN1B3p0IHrgHkNHg9tX5F52040000530398654040.155802BR5913Customer test600062070503***630431C0",
               "qrCodeImageUrl": "https://....",
               "expiresIn":3600
            },
            "boleto":null,
            "providerError":null,
            "providerAuthorization":null,
            "fraudAnalysis":null
         },
         {
            "id":"88f28d71-a64b-42f3-ac57-1cecbbaf1bb4",
            "updatedAt":"2022-09-08T15:31:13.488Z",
            "createdAt":"2022-09-08T15:31:13.488Z",
            "idempotencyKey":"261fccac24c1412f9d23d5eab73418c6",
            "requestId":null,
            "providerId":"5de239ec-b724-453a-96e1-229fe29cdedd",
            "providerType":"MERCADO_PAGO",
            "networkTransactionId":null,
            "amount":150,
            "authorizationCode":null,
            "authorizationNsu":null,
            "requestStatus":"success",
            "requestType":"void",
            "responseTs":null,
            "pix":null,
            "boleto":null,
            "providerError":null,
            "providerAuthorization":null,
            "fraudAnalysis":null
         }
      ],
      "transactionError":null,
      "fraudAnalysisMetadata":null
   }
}

The Pix participants:​

Pix payment flow:​

Payment flow associated with the customer​

Pix refund​

Supported providers for charges via Pix:​

tip

Change of Status Notification​

caution

Refunds​

caution

info

Supported providers for Pix refund​

Testing Pix webhook notifications​

Example of billing via Pix​

Example of refund via Pix​

Example of the refund webhook return​

The Pix participants:

Pix payment flow:

Payment flow associated with the customer

Pix refund

Supported providers for charges via Pix:

Change of Status Notification

Refunds

Supported providers for Pix refund

Testing Pix webhook notifications

Example of billing via Pix

Example of refund via Pix

Example of the refund webhook return