Fundraising/Data and flow/PSP integrations/dLocal

== Overview ==
We are currently working on upgrading our dLocal integration to use the Smart Fields integration.
	
	
== 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
India 	PayTM 	YES[1] 	REDIRECT
India 	Visa 	NO 	DIRECT
India 	Net Banking 	NO 	REDIRECT
India 	Mastercard 	NO 	DIRECT
India 	RuPay 	NO 	DIRECT
India 	Mastercard debit	NO 	DIRECT
Brazil 	Mastercard 	YES 	DIRECT
Brazil 	Visa 	YES 	DIRECT
Brazil 	ELO 	? 	DIRECT
Brazil 	Amex 	YES 	DIRECT
Brazil 	Visa Debit 	NO 	DIRECT
Brazil 	Hipercard 	YES 	DIRECT
Brazil 	Diners 	YES 	N/A
Brazil 	Bradesco** 	NO 	REDIRECT
Brazil 	Pix 	NO 	REDIRECT
Mexico 	Visa 	YES 	DIRECT
Mexico 	Mastercard 	YES 	DIRECT
Mexico 	Visa Debit 	NO 	DIRECT
Mexico 	Amex 	YES 	DIRECT
Argentina	Visa 	 	DIRECT
Argentina	Mastercard 	 	DIRECT
Argentina	BT 	 	REDIRECT
Argentina	Paypal (USD) 	 	N/A
# Dlocal handles recurring payments in India through the India Recurring payment method.
== Payment Methods ==
=== 3DS ===
== Recurring ==
=== Recurring Bank Transfer ===
==== India ====
===== 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:
# Donor selects to put in a recurring donation using UPI Bank Transfer from the DonateWiki page, after which they're redirected to PaymentsWiki.
# Donor enters their personal details (First/Last Name, Email Address, and PAN) on the DI form and clicks continue.
# 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.
# 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.
# Upon successful completion, the Donor is returned to PaymentsWiki where they are redirected to the Thank You page.
# 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.
# Upon receiving the successful IPN message, the listener pushes the IPN message to the jobs-dlocal queue.
# 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.
# 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.
# The UPI Queue Consumer pushes the data with the new next_sched_date to the contribution_recur table and the donations queue.
# 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:
# 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.
# The status for the recurring payment waiting to be charged is set to "Processing" on the contribution_recur table.
# 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.
# 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.
# dLocal sends a IPN message notifying us that the payment is PENDING. We do nothing with this info.
# If the Donor doesn't cancel the payment when they receive the notification, their accounts would be charged on the next day.
# If the charge is successful, dLocal sends an IPN containing the PAID status.
# Upon receiving the successful IPN message, the listener pushes the IPN message to the jobs-dlocal queue.
# 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.
# 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.
# 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 - 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