Jump to content

Fundraising/Data and flow/PSP integrations/dLocal

From Wikitech
dLocal
Original Name dLocal
Our Name dLocal
Current Name dLocal
Payment Methods Credit card, Bank Transfer
Countries AR,BR,CO,CL,IN,MX,PE,UY,ZA
Documentation https://docs.dlocal.com/docs/overview-smart-fields
Production Console https://dashboard.dlocal.com/
Test Console https://dashboard.dlocal.com/
Contact ?

Overview

We are currently working on upgrading our dLocal integration to use the Smart Fields integration.

Smart Fields sequence diagram
Smart fields redirect 3dsecure sequence diagram
Smart fields optional 3dsecure sequence diagram

Payment Rules by Country

Country Currency Minimum Amount Maximum Amount
India INR 10 225000
Default USD 1 3000

Payment Type by Country

Country Payment Type Recurring? Direct or Redirect?
India UPI YES[1] REDIRECT
PayTM YES[1] REDIRECT
Visa NO DIRECT
Net Banking NO REDIRECT
Mastercard NO DIRECT
RuPay NO DIRECT
Mastercard debit NO DIRECT
Brazil Mastercard YES DIRECT
Visa YES DIRECT
ELO ? DIRECT
Amex YES DIRECT
Visa Debit NO DIRECT
Hipercard YES DIRECT
Diners YES N/A
Bradesco** NO REDIRECT
Pix NO REDIRECT
Mexico Visa YES DIRECT
Mastercard YES DIRECT
Visa Debit NO DIRECT
Amex YES DIRECT
Argentina Visa DIRECT
Mastercard DIRECT
BT REDIRECT
Paypal (USD) N/A
  1. Dlocal handles recurring payments in India through the India Recurring payment method.

Payment Methods

3DS

Recurring

Recurring Bank Transfer

India

UML diagram showing the process when a Donor initializes a recurring payment with dLocal
Dlocal India Recurring Initialization
UML diagram showing the process for charging a donor in the recurring payment process
Recurring Charge with Dlocal India Recurring
Initiating a Recurring in India through Bank Transfer (UPI/PayTM)

This is a unique recurring flow for us. The setup follows the iDEAL flow where we get the recurring token on an IPN asynchronously.

Steps:

  1. Donor selects to put in a recurring donation using UPI Bank Transfer from the DonateWiki page, after which they're redirected to PaymentsWiki.
  2. Donor enters their personal details (First/Last Name, Email Address, and PAN) on the DI form and clicks continue.
  3. DonationInterface accepts these details, pushes the data to the pending queue, and begins a transaction with dLocal indicating our intent to start a recurring payment. In a successful response, dLocal returns a redirect url which navigates the Donor to the PayTM/UPI forms.
  4. The donor enters the required information on the PayTM forms. A part of the process on the PayTM/UPI forms requires the Donor to approve the payment notification on their phones.
  5. Upon successful completion, the Donor is returned to PaymentsWiki where they are redirected to the Thank You page.
  6. Meanwhile, the SmashPig IPN listener patiently waits for the Verified IPN message from dLocal indicating that the payment was successful on their end. These message would contain a recurring_payment_token if the payment was successful. We would be using this token to charge the Donor on subsequent recurring payments.
  7. Upon receiving the successful IPN message, the listener pushes the IPN message to the jobs-dlocal queue.
  8. After a short while, the jobs-runner pulls the transaction data from the pending and jobs-dlocal queues. The transaction data from both queues are combined and pushed to the upi-donations queue.
  9. After a short while, the UPI Queue Consumer pulls the message from the upi-donations queue, set the next_sched_date to a date that is 1 month - 24hours from the Date the first donation was put in. This is because the next_sched_date ideally is the date of the next recurring charge, but India Recurring requires merchants to send a pre-notification to the donor 24 hours before a recurring charge is done on the donor's account.
  10. The UPI Queue Consumer pushes the data with the new next_sched_date to the contribution_recur table and the donations queue.
  11. After a short while the Donations Queue consumer pull the data from the donations queue and populates the contribution table with the Donation details.
Charging a Bank Transfer Payment in India (UPI/PayTM)

Once the recurring-payment-token is in the system, we need to send a pre-notification to the donor 24 hours before we charge them. The donor can then approve it (by doing nothing) or cancel their recurring. Once 24 hours has passed we can charge them through our standard flow.

Steps:

  1. The Recurring Processor pulls the record from the contribution_recur table with next_sched_date corresponding to the current date. This record would be the payment to be charged.
  2. The status for the recurring payment waiting to be charged is set to "Processing" on the contribution_recur table.
  3. Processor sends a Pre-notification request to dLocal for the payment. This is because of the India Recurring criteria that requires merchants to send a pre-notification to the donor 24 hours before a recurring charge is done on the donor's account.
  4. dLocal returns a Pending response to the Processor, the Processor in turn updates the payment row in the contribution_recur table, setting the status to "In Progress" and also moving the next_sched_date to a date that is 1 month - 24hours ahead for the next payment.
  5. dLocal sends a IPN message notifying us that the payment is PENDING. We do nothing with this info.
  6. If the Donor doesn't cancel the payment when they receive the notification, their accounts would be charged on the next day.
  7. If the charge is successful, dLocal sends an IPN containing the PAID status.
  8. Upon receiving the successful IPN message, the listener pushes the IPN message to the jobs-dlocal queue.
  9. After a short while, the jobs-runner pulls the transaction data from the jobs-dlocal queue. The transaction data is then pushed to the upi-donations queue.
  10. The UPI consumer pulls the message from the upi-donations queue, updates the status for the payment in the contribution_recur table and pushes the message from the upi-donations queue to the donations queue.
  11. After a short while the Donations Queue consumer pull the data from the donations queue and populates the contribution table with the Donation details.

Recurring Credit Card

Error Messages

300 - Payment was rejected - could be a lot of things, right now insufficient funds also gets pooled into this

321 - Error in acquirer - this was for ones on the monthly flow, when we send the pre-notification before the charge date

322 - Wallet disabled - the donor has cancelled the subscription on their side

IPN

The Dlocal listener authenticates incoming messages and then processes them (refund, chargeback) or sends them along to the jobs-dlocal queue (paid messages, recurring?).

Message Types

  • PAID
  • REJECTED
  • refund
  • chargeback
  • recurring notification IPN?

Audits

We download a nightly report from dlocal (possibly custom just to us).

There is a job dlocal_audit_download.yaml that calls the dlocal_download_nightly part of the tools repo. This connects to dLocals's servers (connection information on civi1002 in etc/fundraising/dlocal-audit.yaml) and downloads the report into the incoming dlocal audit folder

DLocal meetings

Ongoing Google notes

Inital Google notes doc

2023-01-18 Third meeting

2022-12-14 Second Meeting

2022-12-07 Initial Questions

astropay
Original Name Astropay
Our Name astropay
Current Name dLocal
Payment Methods Cards and tons of country-specific bank transfer and cash payment methods
Countries South America, Mexico, and India
Documentation https://dlocal.com/developers/documentation.php?sec=streamline
Production Console ?
Test Console https://merchant.dlocal.com (toggle between test and live mode at top left)
Contact ?

Astropay - Older Integration - APIv1

We're using the deprecated 'Streamline' integration.

The donor's tax ID is a required API parameter. For countries where it's not actually needed, such as Mexico and Peru, we stuff the ID with a random number (has to be random, as repeating the same one would be blocked by DLocal).

Card Logos

The logos linked in the Streamline documentation are low resolution and out of date. To get SVG logos for any new payment methods, check the bottom of the relevant country page (use the country selector at the top right for other countries).

Testing

https://wikitech.wikimedia.org/wiki/Fundraising/Development_tools/Testing#Dlocal