Drip
Drip is an online payment solution that allows the payment of bills in three installments using Pix while providing cashback to your customers. To pay with Drip, the consumer needs to open an account in the Drip system during the payment process.
Malga performs the role of payment intermediary, therefore it does not perform the financial clearance, and an active Drip account is required to use this payment method.
The participants in a Drip transaction
- The payee, a Malga customer who must have an active Drip account.
- The payer, a buyer who is an individual customer.
Drip Payment Flow using the Drip API with direct integration
- To create a transaction with Drip, simply enter the payment method
DRIP
when creating a charge and add the information of the items present in the checkout; - A charge is registered directly in the Drip system and a redirect URL is returned to the registration and payment flow within the Drip platform;
- The payer must confirm the charge directly on the Drip platform;
- After payment confirmation, Drip will send a notification to Malga informing that the payment has been made;
- Subsequently, the receiving Client will be notified that the payment has been made and the collection has been successfully finalized.
This process is described in the following diagrams:
You can consult more information about the integration with checkout in this link.
info
Drip charges are asynchronous by nature, i.e. when creating a new charge you will only have confirmation of the creation of the charge and not of its completion. Authorization or rejection of a charge is notified via the webhooks.
Status change notification
object | event | description |
---|---|---|
transaction | pending | Event sent when the charge is registered and the payment link in Drip is available. |
transaction | authorized | Event sent when confirmation of payment of the charge in Drip is received |
transaction | failed | Event sent when the charge could not be registered due to failure during creation |
transaction | voided | Event sent when the charge is cancelled after having been authorized, producing a financial reimbursement. |
Testing notification receipt of a paid Drip charge
To test your integration with Malga webhooks you can develop your system directly or use a service like request.bin or pipedream.com to initially validate the events sent. Just generate a new endpoint in these services and register a webhook in Malga with the generated endpoint that all events sent will be registered in these services for consultation and debugging.
We allow in the sandbox environment sandbox-api.malga.io
the manual update of transactions created for the status of authorized
and voided
, so you can create a transaction and simulate the desired event.
Request to manually update a Drip charge as paid 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 a charge
Perform a Drip charge using the buyer's data through Charges Service.
curl --location --request POST 'https://api.malga.io/v1/charges' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "d749c775-5c61-448e-9ed4-36b67d085301",
"amount": 100,
"currency": "BRL",
"orderId": "98848683521",
"paymentMethod": {
"paymentType": "drip",
"items": [
{
"id": "123",
"quantity": 1,
"title": "item title",
"unitPrice": 100
}
],
"browser": {
"ipAddress": "127.0.0.1",
"browserFingerprint": "074c1ee676ed4998ab66491013c565e2"
},
"successRedirectUrl": "http://your-service.com/success",
"cancelRedirectUrl": "http://your-service.com/cancel"
},
"paymentSource": {
"sourceType": "customer",
"customer": {
"name": "Nome do Comprador",
"phoneNumber": "xx999999999",
"email": "email@docomprador.com",
"document": {
"number": "11111111111",
"type": "cpf"
},
"address": {
"street": "Rua do Comprador",
"streetNumber": "1",
"zipCode": "00000-140",
"country": "BR",
"state": "RJ",
"district": "Bairro",
"city": "Cidade",
"complement": "complemento"
}
}
}
}'
< HTTP/2 201
{
"id": "c1248092-1769-4b93-9b1d-fabcec356c6c",
"clientId": "<YOUR_CLIENT_ID>",
"merchantId": "d749c775-5c61-448e-9ed4-36b67d085301",
"description": null,
"orderId": "98848683521",
"createdAt": "2023-07-18T23:03:53.035Z",
"amount": 100,
"originalAmount": 100,
"currency": "BRL",
"statementDescriptor": null,
"capture": false,
"isDispute": false,
"status": "pending",
"paymentMethod": {
"paymentType": "drip",
"paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/0f6aa94e-8593-4662-bddd-7bfce2d4c935",
"items": [
{
"id": "123",
"quantity": 1,
"title": "item title",
"unitPrice": 100
}
],
"browser": {
"ipAddress": "127.0.0.1",
"browserFingerprint": "074c1ee676ed4998ab66491013c565e2"
},
"successRedirectUrl": "http://your-service.com/success",
"cancelRedirectUrl": "http://your-service.com/cancel"
},
"paymentSource": {
"sourceType": "customer",
"customerId": "4362a975-9cc7-418f-918b-8ee9585f604e"
},
"transactionRequests": [
{
"id": "449043d9-dc7c-4456-bf58-d8d9a53f15bf",
"createdAt": "2023-07-18T23:03:53.048Z",
"updatedAt": "2023-07-18T23:03:55.501Z",
"idempotencyKey": "9baef27a-9897-4541-9d84-d61b65ffe6fe",
"providerId": "769bce00-678e-4d64-9617-9ce82f4dfcbf",
"providerType": "DRIP",
"transactionId": "9baef27a-9897-4541-9d84-d61b65ffe6fe",
"amount": 100,
"authorizationCode": "f03a3928-460e-42b3-8ece-76cdfdcb5924",
"authorizationNsu": null,
"requestStatus": "success",
"requestType": "pending",
"responseTs": "2436ms",
"drip": {
"paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/0f6aa94e-8593-4662-bddd-7bfce2d4c935",
"items": [
{
"id": "123",
"quantity": 1,
"title": "item title",
"unitPrice": 100
}
],
"browser": {
"ipAddress": "127.0.0.1",
"browserFingerprint": "074c1ee676ed4998ab66491013c565e2"
},
"successRedirectUrl": "http://your-service.com/success",
"cancelRedirectUrl": "http://your-service.com/cancel"
}
}
]
}
caution
For creating Drip transactions, it is mandatory to send paymentSource with customer or identifier of a customer containing a full and valid address.
Drip Refund
Refund requests are synchronous, which means they will be fully proccessed in the same moment the request is made through Malga's API.
When dealing with partial refunds, the transaction will remain authorized
if the transaction amount left in the charge is bigger than 0. Once the transaction amount reaches 0, it's status is updated to voided
.
Drip refund example
When a refund request is made, the API returns a transaction with the status voided
and a transactionRequest
of type void
with the status success
. When the refund request fails for any reason, the transaction remains with the status authorized
, containing a transactionRequest
of type void
with the status failed
."
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": 1200
}'
< HTTP/2 201
{
"id": "7e4930f0-b23c-4378-a3ab-4db684434ded",
"clientId": "<YOUR_CLIENT_ID>",
"merchantId": "d749c775-5c61-448e-9ed4-36b67d085301",
"description": null,
"orderId": "98848683521",
"createdAt": "2023-07-26T12:26:03.938Z",
"amount": 1200,
"originalAmount": 1200,
"currency": "BRL",
"statementDescriptor": null,
"capture": false,
"isDispute": false,
"status": "voided",
"paymentMethod": {
"paymentType": "drip",
"paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/61cad747-7bc3-41b0-a3c5-6a127eacd790",
"browser": {
"ipAddress": "127.0.0.1",
"browserFingerprint": "ab123cd456ef789"
},
"items": [
{
"id": "12345",
"title": "Product 1",
"quantity": 1,
"unitPrice": 300
}
],
"successRedirectUrl": "https://service-example.com/success",
"cancelRedirectUrl": "https://service-example.com/cancel"
},
"paymentSource": {
"sourceType": "customer",
"customerId": "17491cfe-9952-40a9-a56f-c087be2ea693"
},
"transactionRequests": [
{
"id": "3a93edd9-473c-48dd-9b04-62c04d7a3d62",
"createdAt": "2023-07-26T12:40:32.489Z",
"updatedAt": "2023-07-26T12:40:32.489Z",
"idempotencyKey": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f",
"providerId": "07fc7b49-6f27-42c4-b610-ba69af41403e",
"providerType": "DRIP",
"transactionId": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f",
"amount": 1200,
"authorizationCode": null,
"authorizationNsu": null,
"requestStatus": "success",
"requestType": "void",
"responseTs": "460ms"
},
{
"id": "06e955f6-b648-4fdd-b9a8-84c1c75d0f26",
"createdAt": "2023-07-26T12:26:53.557Z",
"updatedAt": "2023-07-26T12:26:53.557Z",
"idempotencyKey": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f",
"providerId": "07fc7b49-6f27-42c4-b610-ba69af41403e",
"providerType": "DRIP",
"transactionId": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f",
"amount": 1200,
"authorizationCode": null,
"authorizationNsu": null,
"requestStatus": "success",
"requestType": "authorization",
"responseTs": null
},
{
"id": "72abedb9-ed78-49d3-98c9-2a83ab59f827",
"createdAt": "2023-07-26T12:26:03.998Z",
"updatedAt": "2023-07-26T12:26:04.717Z",
"idempotencyKey": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f",
"providerId": "07fc7b49-6f27-42c4-b610-ba69af41403e",
"providerType": "DRIP",
"transactionId": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f",
"amount": 1200,
"authorizationCode": "cd3a3d65-d096-4c4c-aef0-abd71b70b49b",
"authorizationNsu": null,
"requestStatus": "success",
"requestType": "pending",
"responseTs": "627ms",
"drip": {
"paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/61cad747-7bc3-41b0-a3c5-6a127eacd790",
"browser": {
"ipAddress": "127.0.0.1",
"browserFingerprint": "ab123cd456ef789"
},
"items": [
{
"id": "12345",
"title": "Product 1",
"quantity": 1,
"unitPrice": 300
}
],
"successRedirectUrl": "https://service-example.com/success",
"cancelRedirectUrl": "https://service-example.com/cancel"
}
}
]
}
Testing refund update
To test a refund update in Malga's sandbox, you should manually update the transaction with a request, as described in the notification receipt.
Request to manually update a Drip charge as refund in the 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"
}'