Use a lightweight WebView to embed dLocal Direct JavaScript SDK into native mobile apps.

By embedding the SDK in a lightweight WebView bridge, the SDK performs sensitive operations, such as card tokenization, so you can call the SDK from native code without collecting or transmitting card data to your servers

The same concepts apply to Android (Kotlin), iOS (Swift), and React Native.

How it works

The integration uses a WebView-based bridge to access the dLocal Direct JavaScript SDK from native code. Here's what happens at the technical level:

• A minimal HTML page loads the dLocal SDK in a WebView.
• Native code sends a message to the WebView with the desired action (e.g., createToken, getBinInformation).
• The SDK processes the request and returns the result (success or error) back to the native app.
• Your app handles the response and forwards the token to your backend for further processing.

Integration overview

1. Your app collects card details securely on-device.
2. The app sends a JSON message to a WebView using a defined message contract.
3. The WebView runs a JS function that uses dLocal’s SDK.
4. The SDK returns a success or error response via the WebView bridge.
5. Your app extracts the result and forwards the token to your backend.

Key concepts

Security considerations

• Never log or store sensitive card data (PANs, CVVs) in the app.
• Card data must be collected on-device and sent only to the SDK. Only the token should leave the device.
• Ensure all traffic is sent over HTTPS (TLS). Avoid injecting or loading any third-party content in the WebView.

SDK operations

The dLocal Direct SDK supports the following operations:

Message contract

Communication between the native app and the WebView follows a standard JSON message structure.

App to WebView

Example request

Example request

{
  "action": "createToken",
  "key": "PUBLIC_KEY",
  "payload": {
    "name": "Jane Doe",
    "cvv": "123",
    "expirationMonth": "12",
    "expirationYear": "30",
    "pan": "4111111111111111",
    "country": "AR"
  }
}

WebView to App

The WebView responds with a JSON string. The native layer should parse this string and handle success or error cases.

Example response

{
  "type": "success",
  "payload": {
    "action": "createToken",
    "result": {
      "card_id": "token_abc123",
      "brand": "VISA",
      "last4": "1111"
    }
  }
}

{
  "type": "error",
  "payload": {
    "message": "Invalid card number",
    "code": "invalid_pan",
    "status": 400
  }
}

Request parameters

createToken(payload)

getBinInformation(args)

Expects: [bin: string, country: string]

getInstallmentsPlan(args)

Expects: [amount: number, currency: string, country: string, bin: string]

Note: The result payloads are provided by the dLocal SDK and may vary by market/feature enablement

Shared Bridge HTML (WebView)

All platforms use a minimal HTML file that includes the dLocal SDK and a handleMessageFromNative(rawJson) function. This function parses the JSON message, calls the SDK, and returns the result via the platform’s WebView messaging API.

Key logic pseudocode

// Loaded inside WebView
<script src="https://js.dlocal.com/direct"></script>;

async function handleMessageFromNative(raw) {
  const { action, key, payload, args } = JSON.parse(raw);
  const direct = window.dlocal(key);
  let result;
  switch (action) {
    case "createToken":
      result = await direct.createToken(payload);
      break;
    case "getBinInformation":
      result = await direct.getBinInformation.apply(null, args || []);
      break;
    case "getInstallmentsPlan":
      result = await direct.getInstallmentsPlan.apply(null, args || []);
      break;
    default:
      throw new Error("Unknown action: " + action);
  }
  // Post back via platform bridge (Android/iOS/RN differ here)
}

Platform-specific implementation

<uses-permission android:name="android.permission.INTERNET" />

class MainActivity : ComponentActivity() {
  private lateinit var webView: WebView

  @SuppressLint("SetJavaScriptEnabled")
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    webView = WebView(this)
    setContentView(webView)

    webView.settings.javaScriptEnabled = true
    webView.settings.domStorageEnabled = true
    webView.webViewClient = WebViewClient()

    webView.addJavascriptInterface(object : Any() {
      @JavascriptInterface
      fun postMessage(message: String) {
        android.util.Log.d("dLocalBridge", message) // parse + update UI
      }
    }, "AndroidBridge")

    webView.loadDataWithBaseURL(null, html, "text/html", "utf-8", null)
  }

  private fun postToWeb(message: JSONObject) {
    val js = "window.handleMessageFromNative(" + JSONObject.quote(message.toString()) + ");"
    webView.evaluateJavascript(js, null)
  }

  fun sendCreateToken(publicKey: String, payload: JSONObject) {
    val message = JSONObject().put("action", "createToken").put("key", publicKey).put("payload", payload)
    postToWeb(message)
  }
}

class ViewController: UIViewController, WKScriptMessageHandler {
  private var webView: WKWebView!

  override func viewDidLoad() {
    super.viewDidLoad()
    let contentController = WKUserContentController()
    contentController.add(self, name: "iosBridge")

    let config = WKWebViewConfiguration()
    config.userContentController = contentController

    webView = WKWebView(frame: view.bounds, configuration: config)
    view.addSubview(webView)
    webView.loadHTMLString(html, baseURL: nil)
  }

  func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
    guard message.name == "iosBridge", let json = message.body as? String else { return }
    print("dLocalBridge:", json) // parse + update UI
  }

  private func postToWeb(json: String) {
    let escaped = json.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
    let js = "window.handleMessageFromNative(" + escaped + ");"
    webView.evaluateJavaScript(js, completionHandler: nil)
  }
}

function PaymentsScreen() {
  const bridgeRef = useRef(null);

  function handleBridgeEvent(event) {
    // event: { type: 'success'|'error', payload: {...} }
  }

  function onCreateToken() {
    bridgeRef.current?.createToken({
      name: "JOHN DOE",
      cvv: "123",
      expirationMonth: "12",
      expirationYear: "30",
      pan: "4111111111111111",
      country: "AR",
    });
  }

  return (
    <>
      {/* Your UI here */}
      <DLocalDirectWebView
        ref={bridgeRef}
        publicKey={YOUR_PUBLIC_KEY}
        onEvent={handleBridgeEvent}
      />
    </>
  );
}

👍

Full platform-specific examples available

Find complete code implementations for Android, iOS, and React Native in the official integration repository of dLocal Direct JS native integrations.

Handling results and errors

The WebView returns a JSON string that must be parsed in the native layer. Always check the type field to determine whether the operation was successful or unsuccessful.

Example handler (generic):

Always parse the WebView’s JSON string and branch on type.

function handleResult(jsonString) {
  const data = JSON.parse(jsonString);
  if (data.type === "success") {
    // use data.payload.result
  } else {
    // show error from data.payload.message
  }
}

Success

On success, type will be success. The result will be found in payload.result.

{
  "type": "success",
  "payload": {
  "result": { /* token or other data */ }
  }
}

Error

On failure, type will be error. Display a user-friendly message and log diagnostic fields like message, code, status.

{
  "type": "error",
  "payload": {
    "message": "Invalid card number",
    "code": "invalid_pan",
    "status": 400,
    "stack": "...optional stack trace..."
  }
}

Going Live

Going server-side with the token

1. On success from createToken, extract the token from payload.result.
2. Send the token to your backend over HTTPS with your order details.
3. Use your backend’s dLocal server-side APIs to create the charge. Do not attempt to charge from the app.

Pre-launch checklist

• Public key configured per environment.
• WebView bridge loads the SDK over HTTPS.
• createToken returns a token; app sends token to backend.
• No secrets or raw card data logged or transmitted to merchant servers.
• Error handling covers type: 'error' with user-friendly messages.

Troubleshooting