===========================================================================
 BD SECURE PAY - Android SDK
===========================================================================

 WHERE IT GOES
   Extract this zip at your Android project root - the folder that has
   settings.gradle and app/ in it. Three files land in place:

     app/src/main/java/com/bdsecurepay/sdk/BdSecurePay.java
     app/src/main/java/com/bdsecurepay/sdk/BdSecurePayCheckoutActivity.java
     app/src/main/java/com/bdsecurepay/example/PaymentExampleActivity.java

   If your module is not called "app", move the java folder into your own
   module - the package names do not have to match your applicationId.

 SETUP
   1. Internet permission, in app/src/main/AndroidManifest.xml, above
      <application>:

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

   2. Register the checkout screen, inside <application>:

        <activity
            android:name="com.bdsecurepay.sdk.BdSecurePayCheckoutActivity"
            android:configChanges="orientation|screenSize|keyboardHidden"
            android:label="Checkout" />

      Nothing else needs to go in the manifest. The checkout screen builds its
      own views in code, so there is no layout XML to add and no resource of
      yours is touched.

   3. Put your API key and gateway URL in the example activity, or wherever you
      keep your config. The key is in your gateway dashboard under Brands.

 USING IT
   BdSecurePay pay = new BdSecurePay("YOUR_API_KEY", "https://payment.yourdomain.com");

   Map<String, Object> metadata = new HashMap<>();
   metadata.put("order_id", orderId);

   Map<String, Object> data = new HashMap<>();
   data.put("cus_name", "John Doe");
   data.put("cus_email", "john@example.com");
   data.put("amount", 100);
   data.put("success_url", "https://yoursite.com/payment/success");
   data.put("cancel_url",  "https://yoursite.com/payment/cancel");
   data.put("webhook_url", "https://yoursite.com/payment/webhook");
   data.put("metadata", metadata);

   pay.createPayment(data, new BdSecurePay.Callback() {
       public void onSuccess(Map<String, Object> response) {
           if (BdSecurePay.isCreated(response)) {
               // open BdSecurePay.paymentUrl(response)
           }
       }
       public void onFailure(String error) { }
   });

   Both calls run on a background thread and hand the answer back on the main
   thread, so you can touch views straight from the callback.

 THE CHECKOUT SCREEN
   BdSecurePayCheckoutActivity opens the payment_url in a WebView and finishes
   the moment the customer lands on your success_url or cancel_url:

     Intent intent = new Intent(this, BdSecurePayCheckoutActivity.class);
     intent.putExtra(BdSecurePayCheckoutActivity.EXTRA_PAYMENT_URL, paymentUrl);
     intent.putExtra(BdSecurePayCheckoutActivity.EXTRA_SUCCESS_URL, successUrl);
     intent.putExtra(BdSecurePayCheckoutActivity.EXTRA_CANCEL_URL,  cancelUrl);
     startActivityForResult(intent, 1001);

   In onActivityResult, RESULT_OK means it landed on your success URL and
   EXTRA_TRANSACTION_ID is set. That is a hint, not proof - call verifyPayment()
   before you give anything away.

   Prefer the system browser? Skip the activity and use an Intent:

     startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(paymentUrl)));

   Then your success_url has to be a deep link back into the app, or your server
   has to be the one that settles the order from the webhook.

 WHAT TO WATCH
   * Never trust what the WebView lands on. ?status=completed can be typed by
     anybody. verifyPayment() is the only thing that decides.
   * Always send webhook_url and handle it on your server. The app is gone the
     moment the customer closes it; a payment approved an hour later has nothing
     to redirect to.
   * PENDING is not a failure. The money has been sent and the merchant has not
     approved it yet. Tell the customer it is being checked, and let your
     server's webhook finish the job.
   * Verify from your server too, not only from the phone. An APK can be
     unpacked - anything the app alone decides can be faked.
   * The API key sits inside the APK. Use a key with an IP whitelist off and
     nothing else attached, and keep any key that can move money on the server.
   * metadata must be a Map with named keys. It is turned into a real JSON
     object for you; a bare Map put into the outer map would serialise wrong and
     the gateway would reject it.
   * The gateway charges BDT. There is no currency field - convert first and
     keep the original amount in metadata.

 CHECKED
   Braces, parentheses and brackets balance in all three files, and every import
   used is imported. Java itself was NOT compiled - there is no JDK or Android
   SDK on the machine this was built on, so it has never been through javac or
   Gradle. Build it once in Android Studio before you ship it.
