Dlocal Documentation Payment Integration
About dLocal:
dLocal is 40% cross-border payments facilitator, 40% technology company and 40% emerging-markets localization experts. That means they are 120% dedicated to delivering a flexible, all-encompassing payments solution that unlocks new revenues and maximizes reach in growth markets.
Implemented Features:
| Feature | Level of Support |
|---|
| Auth | Implemented |
| Sale (Auth+Capture) | Implemented |
| Capture | Implemented |
| Void | Implemented |
| Credit | Implemented |
| Gateway Tokenization | Implemented |
| 3DS Full Integration | Implemented |
Authentication and Security Credentials:
- Merchant xLogin
- Merchant xTransKey
- Secret Key
- notification_url
Supported Parameters:
| Key Name | Format | Mandatory | Descriptions |
|---|
| apiVersion | Numerical | Required | “1.0.1” |
| apiType | Alphabetical | Required | “pxyhpci” |
| userName | Alphanumeric | Required | API Username |
| userPassKey | Alphanumeric | Required | API PassKey |
| pxyCreditCard.creditCardNumber | Numerical | Required | HostedPCI Token Representing Credit Card |
| pxy.CreditCard.cardCodeVerification | Numerical | Optional | HostedPCI Token Representing CVV Code |
| pxyCreditCard.expirationMonth | Numerical | Required | Expiration month with 2 digits for example, for December use “12” |
| pxyCreditCard.expirationYear | Numerical | Required | Expiration year with 4 digits for example, for 2025, use “2025” |
| pxyTransaction.txnCurISO | Alphabetical | Required | 3 letter ISO Currency Code for example, “USD” or “CAD” |
| pxyTransaction.txnAmount | Numerical | Required | Amount to Authorize, for example for $10.50 use 10.50 |
| pxyTransaction.merchantRefId | Numerical | Required | Merchant reference number can be order id or invoice id |
| pxyTransaction.processorRefId | Numerical | Optional | Additional reference number |
| pxyTransaction.txnPayName | Alphanumeric | Required | HostedPCI payment profile name, for example “DEF” |
| pxyTransaction.merchantAccountName | Alphabetical | Optional | Merchant account name for statement |
| pxyTransaction.merchantPhoneNum | Numerical | Optional | Phone number for statement |
| pxyTransaction.merchantProductName | Alphabetical | Optional | Prodcut name that will appear on statement |
| pxyOrder.description | Alphabetical | Optional | Description of charge |
| pxyCustomerInfo.officialDocNumber | Numerical | Required | This is for the tax IDs for Brazil and Mexico |
| pxyCustomerInfo.email | Alphanumeric | Required | Customer’s Email Address |
| pxyCustomerInfo.billingLocation.firstName | Alphabetical | Optional | Customer’s First Name |
| pxyCustomerInfo.billingLocation.lastName | Alphabetical | Optional | Customer’s Last Name |
| pxyCustomerInfo.billingLocation.addressNumber | Numerical | Optional | Customer Street Number |
| pxyCustomerInfo.billingLocation.address | Alphanumeric | Optional | Customer’s Billing Address |
| pxyCustomerInfo.billingLocation.address2 | Alphanumeric | Optional | Secondary address |
| pxyCustomerInfo.billingLocation.city | Alphabetical | Optional | Customer’s Billing City |
| pxyCustomerInfo.billingLocation.state | Alphabetical | Optional | Customer’s Billing State or Province |
| pxyCustomerInfo.billingLocation.zipCode | Numerical | Optional | Customer’s Billing Zip Code or Postal Code |
| pxyCustomerInfo.billingLocation.country | Alphabetical | Optional | Customer’s Billing Country |
Additional Parameters
| KEY NAME | FORMAT | DESCRIPTIONS |
|---|
| pxyTransaction.merchantAccountName | Alphabetical | Required for Soft Descriptors |
| pxyTransaction.merchantProductName | Alphabetical | Required for Soft Descriptors |
| pxyTransaction.merchantPhoneNum | Alphabetical | Required for Soft Descriptors |
API Endpoint URL:
https://[HPCI_API_HOSTENAME]/iSynSApp/paymentAuth.action
API Request Body:
apiVersion=1.0.1&apiType=pxyhpci&userName=[APIuserName]&userPassKey=[APIPassKey]&pxyCreditCard.creditCardNumber=[CreditCardToken]&pxyCreditCard.cardCodeVerification=[CVVToken]&pxyCreditCard.expirationMonth=[ExpiryMonth]&pxyCreditCard.expirationYear=[ExpiryYear]&pxyTransaction.txnCurISO=[Currency]&pxyTransaction.txnAmount=[Amount]&pxyTransaction.merchantRefId=[UniqueMerchantRefID]&pxyTransaction.txnPayName=[ProfileName]&pxyTransaction.txnComment=[ShortComment]&pxyCustomerInfo.billingLocation.firstName=[CustomerFirstName]&pxyCustomerInfo.billingLocation.lastName=[CustomerLastName]&pxyCustomerInfo.billingLocation.address=[BillingStreetAddress]&pxyCustomerInfo.billingLocation.city=[BillingCity]&pxyCustomerInfo.billingLocation.state=[State/Province]&pxyCustomerInfo.billingLocation.zipCode=[ZipCode/PostalCode]&pxyCustomerInfo.billingLocation.country=[Country]&pxyCustomerInfo.officialDocNumber=[Brazil Tax Id]
dLocal Gateway Tokenization
Parameters Required for Gateway Tokenization:
| PARAMETERS | VALUE |
|---|
| pxyCreditCard.creditCardNumber | [HostedPCI Token] |
| pxyCreditCard.cardCodeVerification | [HostedPCI CVV place holder] |
| pxyCreditCard.expirationMonth | [Credit Card expire month] |
| pxyCreditCard.expirationYear | [Credit Card expire year] |
| pxyTransaction.txnPayName | [Profile Name provided by HostedPCI] |
| pxyCustomerInfo.billingLocation.firstName | [Client’s first name as it appears on the card] |
| pxyCustomerInfo.billingLocation.lastName | [Client’s last name as it appears on the card] |
Additional Parameters Required for dLocal Gateway Tokenization:
| PARAMETERS | VALUE |
|---|
| pxyCustomerInfo.billingLocation.address | [billingAddress] |
| pxyCustomerInfo.billingLocation.city | [billing city] |
| pxyCustomerInfo.billingLocation.country | [billing country] |
| pxyCustomerInfo.billingLocation.state | [billing state] |
| pxyCustomerInfo.billingLocation.zipCode | [billing ZIP] |
| pxyCustomerInfo.officialDocNumber | [official Doc Number] |
| pxyCustomerInfo.email | [customer Email] |
dLocal Gateway Tokenization API Call
Request:
pxyCreditCard.creditCardNumber=4444000015201111&pxyCustomerInfo.billingLocation.city=Toronto&userPassKey=[APIPasskey]&pxyCreditCard.expirationMonth=09&userName=[APIUsername]&pxyCreditCard.cardCodeVerification=200&pxyTransaction.txnPayName=DEF_dlocal&pxyCustomerInfo.billingLocation.zipCode=M7H6G5&pxyCustomerInfo.email=null%40email.com&apiVersion=1.0.1&pxyCustomerInfo.officialDocNumber=123412&pxyCreditCard.expirationYear=2022&pxyCustomerInfo.billingLocation.lastName=Customer&pxyCustomerInfo.billingLocation.firstName=Test&pxyCustomerInfo.billingLocation.state=ON&pxyCustomerInfo.billingLocation.address=12596++West+Bayaud+Ave&apiType=pxyhpci&pxyCustomerInfo.billingLocation.country=CAN
Response:
status=success&operId=&tokenId=583719116&mappedCC=4444000015201111&ccBIN=&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=CID-69538e4b-0e67-4b8b-aa52-fdae30eeed05&pxyResponse.processorType=dlocalResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3DVISA&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=success&pxyResponse.responseStatus.name=&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=CID-69538e4b-0e67-4b8b-aa52-fdae30eeed05&pxyResponse.responseAVS1=&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=%7B%22card_id%22%3A%22CID-69538e4b-0e67-4b8b-aa52-fdae30eeed05%22%2C%22holder_name%22%3A%22Test+Customer%22%2C%22expiration_month%22%3A9%2C%22expiration_year%22%3A2022%2C%22brand%22%3A%22VI%22%2C%22last4%22%3A%221111%22%7D&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=%7B%22card_id%22%3A%22CID-69538e4b-0e67-4b8b-aa52-fdae30eeed05%22%2C%22holder_name%22%3A%22Test+Customer%22%2C%22expiration_month%22%3A9%2C%22expiration_year%22%3A2022%2C%22brand%22%3A%22VI%22%2C%22last4%22%3A%221111%22%7D&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF_dlocal&pxyResponse.responseStatus.code=&pxyResponse.threeDSSRS=
3DS 2 implementation
Dlocal 3DS 2 has been implemented HostedPCI.
The parameters listed on the page are required along with the mandatory AUTH transaction parameters to make a successful 3DSecure transaction.
3DS 2.0 “Verifyenroll” Call
| PARAMETERS | VALUE |
|---|
| pxyTransaction.txnPayName | [3ds payment profile name] |
| pxyThreeDSecAuth.actionName | [verifyenroll] |
| pxyThreeDSecAuth.callMode | reportall |
| pxyThreeDSecAuth.merchantSessionId | [Optional for Dlocal 3DS – can be seen in return Url] |
| pxyCustomerInfo.officialDocNumber | [Optional for Dlocal for certain Countries.] |
3DS 2.0 “verifyresp” Call
| PARAMETERS | VALUE |
|---|
| pxyTransaction.txnPayName | [3ds payment profile name] |
| pxyThreeDSecAuth.actionName | [verifyresp] |
| pxyThreeDSecAuth.messageId | [] |
| pxyThreeDSecAuth.authTxnId | [returned in the Verifyenroll call] |
3DS 2.0 Verifyenroll Request Call:
pxyCreditCard.creditCardNumber=400000..........&pxyOrder.orderItems[0].itemPrice=65.65&pxyCustomerInfo.billingLocation.city=Toronto&pxyOrder.orderItems[0].itemQuantity=1&pxyOrder.description=Test+Order&pxyOrder.orderItems[0].itemDescription=Best&pxyOrder.orderItems[0].itemTaxable=N&pxyOrder.invoiceNumber=Order%3A+AAA69142615&userPassKey=9dG-............................&pxyThreeDSecAuth.authSessionId=0_8884c755-3b4c-41ce-87fc-aeacf512b513&pxyTransaction.txnAmount=65.65&pxyCreditCard.cardCodeVerification=737&pxyTransaction.txnPayName=DEF&pxyCustomerInfo.browserAcceptHeader=text%2Fhtml%2Capplication%2Fxhtml%2Bxml%2Capplication%2Fxml%3Bq%3D0.9%2Cimage%2Favif%2Cimage%2Fwebp%2Cimage%2Fapng%2C*%2F*%3Bq%3D0.8%2Capplication%2Fsigned-exchange%3Bv%3Db3%3Bq%3D0.9&pxyThreeDSecAuth.actionName=verifyenroll&apiVersion=1.0.1&pxyCustomerInfo.customerIP=127.0.0.1&pxyCustomerInfo.billingLocation.firstName=AUTHORISED&pxyCustomerInfo.billingLocation.country=CA&pxyCustomerInfo.billingLocation.phoneNumber=4168351525&pxyOrder.orderItems[0].itemName=item&pxyOrder.totalAmount=65.65&pxyCreditCard.expirationMonth=03&pxyCustomerInfo.customerId=hpcitest1&userName=[APIUsername]&pxyTransaction.txnCurISO=GBP&pxyCustomerInfo.billingLocation.zipCode=M9K8U6&pxyCustomerInfo.browserUserAgentHeader=Mozilla%2F5.0+%28X11%3B+Linux+x86_64%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F83.0.4103.61+Safari%2F537.36&pxyCustomerInfo.email=hpcitest1%40mailinator.com&pxyOrder.orderItems[0].itemId=Item-1-AAA69142615&pxyCreditCard.cardType=VISA&pxyThreeDSecAuth.authOrderId=67UDMNKVH1RE1001821&pxyCreditCard.expirationYear=2030&pxyThreeDSecAuth.callMode=reportall&pxyCustomerInfo.billingLocation.address=22+Hilltop+St&apiType=pxyhpci&pxyTransaction.merchantRefId=AAA69142615