Fundraising/Data and flow/PSP integrations/dLocal

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	?

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

Dlocal handles recurring payments in India through the India Recurring payment method.

Payment Methods

3DS

Recurring

Recurring Bank Transfer

India


Dlocal India Recurring Initialization
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:

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