Unlock the Power of API Support: Streamlining Your Operations Effortlessly! Access a Wealth of Tools and Resources to Optimize Your Workflow.

APIs and SDK

<h4>You need to share the package name for the Android project with the NearPay team.</h4>

Which package name should I share ?

<h4>You can see all transactions in client dashboard, also you can list it using the API</h4><p><a target="_blank" rel="noopener noreferrer nofollow" href="https://docs.nearpay.io/api-endpoints/api#get-list-transactions"><strong>here</strong></a></p>

Where can I see my transactions ?

<h4>Whenever the SDK environment is on production , if the developer mode is not off then you can not communicate with Nearpay to make any transactions .</h4>

When should the developer mode be turned off?

<h4>When NearPay service is no longer needed . For example when the users logout from your app , they need to logout from NearPay service (means the terminal) as well. So, they cannot use the service when they are logged out .</h4>

When do I need to logout ?

<h4>Payment reconciliation is an accounting process that verifies account balances to ensure all sets of records are true, consistent, and up-to-date. Businesses can reconcile their accounts daily, weekly, or monthly.</h4>

What is reconciliation ?

<h4>Customer reference number is a number that identifies your customer ID, so you can assign any number you want as customer reference number , also it is optional so you can leave it empty if you wish. You can use customer reference number in Purchase and Refund.</h4>

What is a customer reference number ?

<h4>JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.</h4>

What is JWT ?

<h4>We have three main environments:</h4><ul><li><p>SandBox: where you integrate the SDK on Sandbox Environment</p></li><li><p>Testing: we will test your app with Saudi Payment and get it approved</p></li><li><p>Production : here you can go live</p></li></ul>

What are the different environments ?

<h4>You can create the keys using Security section, public keys are the keys that you are going to share it with us and private keys are going to be used in generating the JWT to communicate with NearPay when using any function like purchase , refund , etc.</h4>

What are public keys and private keys ?

<h4>You can use it with android 10 or higher.</h4>

What Android version can be used with the SDK ?

<p>In order to get the full list of objects you need to show the objects in each page, as the API returns 30 objects per one page. So you need to see how many pages are there, and access each page to view its objects.</p><p>To be able to paginate you need to use these parameters:</p><table style="minWidth: 75px"><colgroup><col><col><col></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Parameter</p></th><th colspan="1" rowspan="1"><p>type</p></th><th colspan="1" rowspan="1"><p>description</p></th></tr><tr><td colspan="1" rowspan="1"><p>page</p></td><td colspan="1" rowspan="1"><p>number</p></td><td colspan="1" rowspan="1"><p>Defines which page you want to access</p></td></tr><tr><td colspan="1" rowspan="1"><p>limit</p></td><td colspan="1" rowspan="1"><p>number</p></td><td colspan="1" rowspan="1"><p>Defines how many objects you want to list per page</p></td></tr></tbody></table><h2>Pagination Example</h2><p>Let’s assume we have 120 transactions, and you want to show 25 transactions per page. To do so follow these steps:</p><p>1- Use List Transactions endpoint, you will see pages object in the end of the response:</p><pre><code class="language-jsx"> "pages": {
        "total": 2,
        "current": 1
    }
</code></pre><p>To explain this object:</p><table style="minWidth: 50px"><colgroup><col><col></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>key</p></th><th colspan="1" rowspan="1"><p>description</p></th></tr><tr><td colspan="1" rowspan="1"><p>pages</p></td><td colspan="1" rowspan="1"><p>Pages information object</p></td></tr><tr><td colspan="1" rowspan="1"><p>total</p></td><td colspan="1" rowspan="1"><p>number of pages</p></td></tr><tr><td colspan="1" rowspan="1"><p>current</p></td><td colspan="1" rowspan="1"><p>Current page of the response</p></td></tr></tbody></table><p>We can tell from the response that we have two pages and we are in the first page. Now let’s see how we can go to the next page:</p><p>2- Add parameter page=2 to the request:</p><pre><code>https://sandbox-api.nearpay.io/v1/clients-sdk/transactions?page=2 </code></pre><p>You will get the second page objects, and to make sure, check the pages object, “current” should show 2:</p><pre><code class="language-jsx">"pages": {
        "total": 2,
        "current": 2
    }
</code></pre><h2>Limitation Example</h2><p>Now if you want to limit the response of each page to 25 objects, you can do that by adding this parameter to the request:</p><pre><code> https://sandbox-api.nearpay.io/v1/clients-sdk/transactions?limit=25</code></pre>

How to use Pagination?

<h4>You can just call purchase and our UI will show up to make a payment.</h4>

How can I make a purchase ?

<h4>Go to Settings - &gt; Apps - &gt; Payment Plugin -&gt; Version</h4>

How can I know the version of the payment plugin ?

<h4>NearPay Team will send you a client uuid once we have received the public key and the android package name.</h4>

How can I get the client uuid ?

<p><a target="_blank" rel="noopener noreferrer nofollow" href="https://docs.nearpay.io/sdk/security#connect"><strong>Follow the instructions</strong></a></p>

How can I generate JWT ?

<h4>We have a feature to enable or disable the receipt ui and all our functions, just set enableReceiptUi to false .</h4>

How can I disable the ui of the receipt ?

<h4>You can define the environment in Nearpay project</h4><pre><code class="language-kotlin">val nearpay = NearPay(this, jwt, Locale.getDefault(), Environments.SANDBOX)</code></pre>

How can I change the environment ?

<p>You can retrieve a transaction for any purpose like making sure it’s approved and so on. There are three methods to retrieve a transaction, let’s discuss them one by one:</p><h2><br>1- Retry Using transactionId</h2><p>The retry policy enables you to inquire about a transaction if it has been done or not. Sometimes you face cases like:</p><ul><li><p>Device battery dies</p></li><li><p>Crash in your App</p></li></ul><p>Let’s suppose you tapped a card and did a transaction but the device closed all of a sudden. So you will retry by following these steps:</p><ol><li><p>When you do a purchase transaction you pass a transactionId that’s being generated locally, you will store this value locally after it’s being generated as you will need to pass it again later to inquire. (Please check the code below that shows transactionId)</p></li></ol><pre><code>Long amount = 100L; // [Required] ammount you want to set . 
String customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6753"; // [optional] any number you want to add as a refrence
Boolean enableReceiptUi = true; // [optional] true will enable the ui and false will disable
Boolean enableReversal = true; // it will allow you to enable or disable the reverse button
Long finishTimeOut = 10L; // Add the number of seconds 
UUID transactionId = java.util.UUID.randomUUID(); // You can add your UUID here which allows you to ask about the transaction again using the same UUID
Boolean enableUiDismiss = true ;// [optional] it will allow you to control dismissing the UI

nearPay.purchase(amount, customerReferenceNumber, enableReceiptUi, enableReversal, finishTimeOut,transactionId,enableUiDismiss, new PurchaseListener() {
    @Override
    public void onPurchaseApproved(@NonNull TransactionData transactionData) {
        // if you wish to get the receipt in Json format use ReceiptUtilsKt.toJson(list.get(0))
        //write your code here. 
    }

    @Override
    public void onPurchaseFailed(@NonNull PurchaseFailure purchaseFailure) {
        if (purchaseFailure instanceof PurchaseFailure.GeneralFailure) {
            // when there is General error .  
        }
        else if (purchaseFailure instanceof PurchaseFailure.PurchaseDeclined) {
        // when the payment declined.
        }
        else if (purchaseFailure instanceof PurchaseFailure.PurchaseRejected) {
            // when the payment rejected.
        }
        else if (purchaseFailure instanceof PurchaseFailure.AuthenticationFailed) {
            // when the authentication failed .
            // You can use the following method to update your JWT
            nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
        }
        else if (purchaseFailure instanceof PurchaseFailure.InvalidStatus) {
            // you can get the status using the following code 
            List&lt;StatusCheckError&gt; status = ((PurchaseFailure.InvalidStatus) purchaseFailure).getStatus();
        }
    }
});</code></pre><p>If you get a response that the purchase is approved or declined, you don’t need to pass the same transactioId. Pass a new transactionId to do a new transaction. If you get a response other than approved or declined, move to step 3.</p><ol start="2"><li><p>Execute the purchase function again but pass the transactionId that you stored from the previous transaction.</p></li><li><p>If you get a receipt that means the original transaction is done successfully.</p></li><li><p>If it asks you again to tap the card that means the original transaction has been failed and you need to retry again.</p></li></ol><h2>2- Get Transaction By Customer Reference Number</h2><p>When you create a purchase transaction there’s a string value that you can pass (Optional), which is the customer reference number (Please find in the code below and here is its <a target="_blank" rel="noopener noreferrer nofollow" href="https://docs.nearpay.io/guides/sdk#purchase">reference in the docs</a>)</p><pre><code>Long amount = 100L; // [Required] ammount you want to set . 
String customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6753"; // [optional] any number you want to add as a refrence
Boolean enableReceiptUi = true; // [optional] true will enable the ui and false will disable
Boolean enableReversal = true; // it will allow you to enable or disable the reverse button
Long finishTimeOut = 10L; // Add the number of seconds 
UUID transactionId = java.util.UUID.randomUUID(); // You can add your UUID here which allows you to ask about the transaction again using the same UUID
Boolean enableUiDismiss = true ;// [optional] it will allow you to control dismissing the UI

nearPay.purchase(amount, customerReferenceNumber, enableReceiptUi, enableReversal, finishTimeOut,transactionId,enableUiDismiss, new PurchaseListener() {
    @Override
    public void onPurchaseApproved(@NonNull TransactionData transactionData) {
        // if you wish to get the receipt in Json format use ReceiptUtilsKt.toJson(list.get(0))
        //write your code here. 
    }

    @Override
    public void onPurchaseFailed(@NonNull PurchaseFailure purchaseFailure) {
        if (purchaseFailure instanceof PurchaseFailure.GeneralFailure) {
            // when there is General error .  
        }
        else if (purchaseFailure instanceof PurchaseFailure.PurchaseDeclined) {
        // when the payment declined.
        }
        else if (purchaseFailure instanceof PurchaseFailure.PurchaseRejected) {
            // when the payment rejected.
        }
        else if (purchaseFailure instanceof PurchaseFailure.AuthenticationFailed) {
            // when the authentication failed .
            // You can use the following method to update your JWT
            nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
        }
        else if (purchaseFailure instanceof PurchaseFailure.InvalidStatus) {
            // you can get the status using the following code 
            List&lt;StatusCheckError&gt; status = ((PurchaseFailure.InvalidStatus) purchaseFailure).getStatus();
        }
    }
});</code></pre><p>This reference can be used as a unique identifier that you can use as a query in order to retrieve the transaction to check its details. To do so please use the get list of transactions from <a target="_blank" rel="noopener noreferrer" class="notion-link-token notion-focusable-token notion-enable-hover" href="https://docs.nearpay.io/guides/sdk#get-list-of-transactions">here</a> and pass the customer reference number, you will get the specific transaction for this reference. Here is the list transactions function:</p><p></p><pre><code>
String customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6753"; // [optional] any number you want to add as a refrence
nearPay.getTransactionListPage( pages, page_size,null,null, customerReferenceNumber,new GetTransactionPageListener() {

   @Override
   public void onSuccess(@Nullable TransactionBannerList transactionBannerList) {
                      
   }

   @Override
   public void onFailure(@NonNull GetDataFailure getDataFailure) {
       if (getDataFailure instanceof GetDataFailure.GeneralFailure) {
                            // when there is general error .
        }
        else if(getDataFailure instanceof GetDataFailure.FailureMessage){
                            // when there is FailureMessage
        }
        else if(getDataFailure instanceof GetDataFailure.InvalidStatus){
                            // you can get the status using following code
        List&lt;StatusCheckError&gt; status = ((GetDataFailure.InvalidStatus) getDataFailure).getStatus();
        }
        else if(getDataFailure instanceof GetDataFailure.AuthenticationFailed){
                            // when the Authentication is failed
                            // You can use the following method to update your JWT
         nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
            }
         }
      });</code></pre><h2>3- Using Webhooks</h2><p>You can get notification of the transaction payload whenever an event is triggered like transaction approved, transaction declined and so on.</p><p>To subscribe to these events please go to your dashboard and follow these steps:</p><ol><li><p>Go to <strong>Events</strong></p></li><li><p>Press on the <strong>Add button</strong></p></li><li><p>A popup window will show up that shows: <strong>Event</strong>: The event type you want to subscribe to <strong>Method</strong>: The HTTP method <strong>URL</strong>: your url that will receive the notifications</p></li><li><p>Press on <strong>create webhook</strong> after filling this data</p></li></ol><p><strong>Example of payment approved notification payload (You can find more details </strong><a target="_blank" rel="noopener noreferrer" class="notion-link-token notion-focusable-token notion-enable-hover" href="https://docs.nearpay.io/api-endpoints/webhook"><strong>here</strong></a><strong>)</strong></p><pre><code>{
  "id": "c98b2091-27fc-5642-b3ac-91f1d2eb07d3",
  "pan": "5069 68** **** 5760",
  "tid": "0200066700000667",
  "qr_code": "https://sandbox-api.nearpay.io/ui/receipt/c43b2091-6742-27fc-b3ac-91f1d2eb07d3",
  "currency": {
    "arabic": "ر.س",
    "english": "SAR"
  },
  "end_date": "20/06/2023",
  "end_time": "11:56:03",
  "merchant": {
    "id": "100000000000001",
    "name": {
      "arabic": "NearPay Merchant Arabic",
      "english": "NearPay Merchant"
    },
    "address": {
      "arabic": "4321",
      "english": "KAFD"
    },
    "category_code": "0763"
  },
  "kernel_id": "02",
  "entry_mode": "CONTACTLESS",
  "pan_suffix": "",
  "start_date": "20/06/2023",
  "start_time": "11:56:03",
  "action_code": "000",
  "card_scheme": {
    "id": "P1",
    "name": {
      "arabic": "مدى",
      "english": "mada"
    }
  },
  "is_approved": true,
  "is_refunded": false,
  "is_reversed": false,
  "transaction": {
    "id": "59835"
  },
  "amount_other": {
    "label": {
      "arabic": "مبلغ النقد",
      "english": "NAQD AMOUNT"
    },
    "value": "0.00"
  },
  "approval_code": {
    "label": {
      "arabic": "رمز الموافقة",
      "english": "Approval Code"
    },
    "value": "790200"
  },
  "status_message": {
    "arabic": "مقبولة",
    "english": "Approved"
  },
  "thanks_message": {
    "arabic": "شكرا لاستخدامكم مدى",
    "english": "Thank you for using mada"
  },
  "card_expiration": "24/09",
  "receipt_line_one": {
    "arabic": "",
    "english": ""
  },
  "receipt_line_two": {
    "arabic": "",
    "english": ""
  },
  "transaction_type": {
    "id": "00",
    "name": {
      "arabic": "شراء",
      "english": "PURCHASE"
    }
  },
  "transaction_uuid": "c43b6431-23a7-4a54-96ff-e23bb0d1015e",
  "amount_authorized": {
    "label": {
      "arabic": "مبلغ الشراء",
      "english": "PURCHASE AMOUNT"
    },
    "value": "5.00"
  },
  "card_scheme_sponsor": "INMA",
  "verification_method": {
    "arabic": "لا يتطلب التحقق",
    "english": "NO VERIFICATION REQUIRED"
  },
  "save_receipt_message": {
    "arabic": "يرجى الاحتفاظ بالفاتورة",
    "english": "please retain receipt"
  },
  "application_cryptogram": "3DCFAEE023EC843D",
  "application_identifier": "A0000004321912",
  "customer_reference_number": null,
  "payment_account_reference": "34R0380DORHB43PPOD0NL7SY71VK6",
  "system_trace_audit_number": "000180",
  "retrieval_reference_number": "000000034523",
  "cryptogram_information_data": "80",
  "pos_software_version_number": "1.0.0",
  "terminal_verification_result": "8020000001",
  "transaction_state_information": "0000",
  "cardholader_verfication_result": "1F0256"
}</code></pre>

How Can I Retry a Transaction?

<h4>No , user can not exceed the paid amount .</h4>

Can the user refund more than the paid amount in the transaction?

<h4>Multiple refunds is possible as long as it doesn’t exceed the paid amount</h4>