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