# Billing software docs Billing software that helps businesses collect receivables faster, organize expenses, automate vendor pay outs & streamline GST filing. ### Getting started with billing software To get started with using Swipez APIs you would need an billing software account. Creating an account is free and you create one with a few clicks. [Get your own free billing software](https://www.swipez.in/register). Swipez billing software is one of the [best billing software product](https://www.swipez.in/billing-software) made especially considering the requirements for a small or medium sized business. Billing software starts by organizing your business contact information like Customers, Vendors and Franchises. This contact information is used to create invoices or expense entries into your billing software account. Swipez billing software comes built in with online payments for faster payment collections and also has a facility to make payouts to vendors or franchises. Over 15,000 businesses use Swipez billing software to bill their customers on a daily basis. Customers are able to make online payments via the bills they receive and the business in turn gets paid faster. Invoice formats are completely customizable and can be setup as per the needs of the business. [Billing software help desk](https://helpdesk.swipez.in/help) provides an in depth walk through of the features that are available for your business. All key aspects of your billing software can be controlled via APIs which are listed below. ### Billing software API listing [Customer management ](https://docs.swipez.in/customer-management): Manage your customer data centrally. Sync customer contact information with Swipez and other systems with ease. [Invoicing ](https://docs.swipez.in/invoicing): Use the extensible and completely configurable Swipez invoicing engine for your application. Create invoices, send notifications to customers, manage subscriptions and more. ### Payment collection API listing [Payment gateway ](https://docs.swipez.in/payment-gateway): Payment collection specific APIs and toolkits to integrate your application with online payments. ### Expense management and Payouts API listing [Payouts ](https://docs.swipez.in/payouts): Make payouts to one or multiple beneficiaries using the Payouts API. # Invoicing Learn more about invoicing APIs and their usage. ### Guidelines Below are some of the points you must be aware of while calling Swipez APIs: * All API requests and responses are in JSON format. * POST requests should include `ContentType: application/json` * All API response have **status, message,** and **data**. * Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey). ### Rate limiting The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change. ### Quick Reference | URL | HTTP Verb | Functionality | | --------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------- | | [/api/v3/merchant/invoice/save](https://docs.swipez.in/invoicing-1#save-invoice) | POST | To create invoice. | | [/api/v3/merchant/invoice/update](https://docs.swipez.in/invoicing-1#update-invoice) | POST | To update created invoice. | | [/api/v2/merchant/invoice/settle](https://docs.swipez.in/invoicing-1#settle-invoice) | POST | To settle invoice. | | [/api/v1/merchant/invoice/detail](https://docs.swipez.in/invoicing-1#get-invoice-details) | POST | To get invoice details. | | [/api/v1/merchant/invoice/getlist](https://docs.swipez.in/invoicing-1#invoice-list) | POST | To get invoice list. | | [/api/v1/merchant/subscription/save](https://app.gitbook.com/@swipez/s/swipez-docs/~/drafts/-MUmqisdIkG-CEp_IN8M/invoicing#save-subscription) | POST | To save recurring invoice. | | [/api/v3/merchant/invoice/deleteInvoice](/invoicing#delete-invoice) | POST | To delete or cancel invoice | ## Save invoice `POST` `/api/v3/merchant/invoice/save` This endpoint allows you to save and send invoices to customers.\ \ **Download invoice format JSON with below steps.**\ 1\. Go to invoice format list 2\. Click on action button.\ 3\. Choose "Upload Invoice v3 JSON" option.
#### Request Body | Name | Type | Description | | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret access key. | | template\_id | string | Invoice format encrypted key. | | invoice | array | Array of multiple invoices. | | customer\_code | string | Customer unique number. | | bill\_cycle\_name | string | Billing cycle name eg. Feb21 | | franchise\_id | integer | If you enable "Franchise" plugin in your invoice format you can set franchise id which you will get from franchise list. | | vendor\_id | integer | If you enable "Vendor" plugin in your invoice format you can set vendor id which you will get from vendor list. | | bill\_date | string | Bill date (in the format of YYYY-mm-dd) | | due\_date | string | Due date (in the format of YYYY-mm-dd) | | notify\_patron | number | Notification send to customer value 1 for yes 0 for no. | | custom\_header\_fields | string | If you added custom field in invoice format you can set value for that column. | | particular\_rows | string | Set values for particular rows as per invoice format like Item, Description, Cost etc. | | advance\_received | integer | If you enable "Prepaid invoice" plugin in invoice format you can set received amount. | | enable\_partial\_payment | integer | If you enable "Partial payment" plugin in invoice format you can set 1 for enable 0 for disable partial payment for this invoice | | partial\_min\_amount | string | Partial minimum amount. | | cc\_email | array | If you enable "CC email" plugin in your invoice format you can set emails for cc in this invoice. | | coupon | array | If you enable "Coupon" plugin in your invoice format you can set coupon id or coupon details in this array. | | deduct\_rows | array | If you enable "Deductible" plugin in your invoice format you can set deduct tax details like tax name, percent, applicable. | | tax\_rows | array | Add taxes to invoice eg. Tax name, percentage, applicable on | | new\_customer | array | If customer does not exist in Swipez then you can add customer details | | settlement | array | If you want to settle invoice immediately after creating invoice | {% tabs %} {% tab title="200 Invoice saved successfully." %} ``` { "reqtime": "2021-03-01 18:59:41", "resptime": "2021-03-01 18:59:41", "srvrsp": [ { "invoice_id": "R000029148", "code": "12121", "bill_date": "2021-03-01", "patron_name": "Rohit Sharma", "email_id": "user@swipez.in", "mobile": "9999999999", "amount": "590.00", "short_url": "https://go.swipez.in/9vb786" } ], "errcode": 0, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v3/merchant/invoice/save' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "template_id": "", "invoice": [ { "customer_code": "Cust-1", "bill_cycle_name": "Feb 21", "bill_date": "2021-02-01", "due_date": "2021-02-05", "invoice_properties": { "notify_patron": "1" }, "custom_header_fields": [ { "id": "1853191", "name": "Invoice no", "type": "text", "value": "INV-5" } ], "particular_rows": [ { "item": "Product name", "sac_code": "9899", "description": "Product description", "gst": "18", "total_amount": "1500.00" } ], "tax_rows": [ { "name": "IGST@18%", "percentage": "18.00", "applicable_on": "1500.00" } ], "new_customer": { "customer_code": "", "customer_name": "", "email": "", "mobile": "", "address": "", "city": "", "state": "", "zipcode": "", "custom_fields": [ { "id": "845", "name": "GST", "type": "gst", "value": "" } ] }, "settlement": { "access_key_id": "", "secret_access_key": "", "invoice_id": "", "paid_date": "2022-02-23", "amount": "18.00", "mode": "Online", "bank_name": "", "bank_ref_no": "1234567", "cheque_no": "", "cash_paid_to": "", "notify": "1", "attach_invoice_pdf": "1" } } ] }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v3/merchant/invoice/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "template_id": "", "invoice": [ { "customer_code": "Cust-1", "bill_cycle_name": "Feb 21", "bill_date": "2021-02-01", "due_date": "2021-02-05", "invoice_properties": { "notify_patron": "1" }, "custom_header_fields": [ { "id": "1853191", "name": "Invoice no", "type": "text", "value": "INV-5" } ], "particular_rows": [ { "item": "Product name", "sac_code": "9899", "description": "Product description", "gst": "18", "total_amount": "1500.00" } ], "tax_rows": [ { "name": "IGST@18%", "percentage": "18.00", "applicable_on": "1500.00" } ], "new_customer": { "customer_code": "", "customer_name": "", "email": "", "mobile": "", "address": "", "city": "", "state": "", "zipcode": "", "custom_fields": [ { "id": "845", "name": "GST", "type": "gst", "value": "" }, { "id": "846", "name": "Company Name", "type": "company_name", "value": "" } ] }, "settlement": { "access_key_id": "", "secret_access_key": "", "invoice_id": "", "paid_date": "2022-02-23", "amount": "18.00", "mode": "Online", "bank_name": "", "bank_ref_no": "1234567", "cheque_no": "", "cash_paid_to": "", "notify": "1", "attach_invoice_pdf": "1" } } ] }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Update invoice `POST` `/api/v3/merchant/invoice/update` \ This endpoint allows you to update created invoice.\ \ Download invoice format JSON with below steps. \ 1\. Go to invoice format list \ 2\. Click on action button. \ 3\. Choose "Update Invoice v3 JSON" option. #### Request Body | Name | Type | Description | | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | invoice\_id | string | Swipez system generated invoice id. | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret access key. | | template\_id | string | Invoice format encrypted key. | | invoice | array | Array of invoice detail. | | customer\_code | string | Customer unique number. | | bill\_cycle\_name | string | Billing cycle name eg. Feb21 | | franchise\_id | integer | If you enable "Franchise" plugin in your invoice format you can set franchise id which you will get from franchise list. | | vendor\_id | integer | If you enable "Vendor" plugin in your invoice format you can set vendor id which you will get from vendor list. | | bill\_date | string | Bill date (in the format of YYYY-mm-dd) | | due\_date | string | Due date (in the format of YYYY-mm-dd) | | notify\_patron | number | Notification send to customer value 1 for yes 0 for no. | | custom\_header\_fields | string | If you added custom field in invoice format you can set value for that column. | | particular\_rows | string | Set values for particular rows as per invoice format like Item, Description, Cost etc. | | advance\_received | integer | If you enable "Prepaid invoice" plugin in invoice format you can set received amount. | | enable\_partial\_payment | integer | If you enable "Partial payment" plugin in invoice format you can set 1 for enable 0 for disable partial payment for this invoice | | partial\_min\_amount | string | Partial minimum amount. | | cc\_email | array | If you enable "CC email" plugin in your invoice format you can set emails for cc in this invoice. | | coupon | array | If you enable "Coupon" plugin in your invoice format you can set coupon id or coupon details in this array. | | deduct\_rows | array | If you enable "Deductible" plugin in your invoice format you can set deduct tax details like tax name, percent, applicable. | | tax\_rows | array | Add taxes to invoice eg. Tax name, percentage, applicable on | | new\_customer | array | If customer does not exist in Swipez then you can add customer details | {% tabs %} {% tab title="200 Invoice saved successfully." %} ``` { "reqtime": "2021-03-01 18:59:41", "resptime": "2021-03-01 18:59:41", "srvrsp": [ { "invoice_id": "R000029148", "code": "12121", "bill_date": "2021-03-01", "patron_name": "Rohit Sharma", "email_id": "user@swipez.in", "mobile": "9999999999", "amount": "590.00", "short_url": "https://go.swipez.in/9vb786" } ], "errcode": 0, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v3/merchant/invoice/update' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "invoice_id": "", "invoice": { "customer_code": "Cust-1", "bill_cycle_name": "Feb 21", "bill_date": "2021-02-01", "due_date": "2021-02-05", "invoice_properties": { "notify_patron": "1" }, "custom_header_fields": [ { "id": "1853191", "name": "Invoice no", "type": "text", "value": "INV-5" } ], "particular_rows": [ { "item": "Product name", "sac_code": "9899", "description": "Product description", "gst": "18", "total_amount": "1500.00" } ], "tax_rows": [ { "name": "IGST@18%", "percentage": "18.00", "applicable_on": "1500.00" } ], "new_customer": { "customer_code": "", "customer_name": "", "email": "", "mobile": "", "address": "", "city": "", "state": "", "zipcode": "", "custom_fields": [ { "id": "845", "name": "GST", "type": "gst", "value": "" }, { "id": "846", "name": "Company Name", "type": "company_name", "value": "" } ] } } }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v3/merchant/invoice/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "invoice_id": "", "invoice": { "customer_code": "Cust-1", "bill_cycle_name": "Feb 21", "bill_date": "2021-02-01", "due_date": "2021-02-05", "invoice_properties": { "notify_patron": "1" }, "custom_header_fields": [ { "id": "1853191", "name": "Invoice no", "type": "text", "value": "INV-5" } ], "particular_rows": [ { "item": "Product name", "sac_code": "9899", "description": "Product description", "gst": "18", "total_amount": "1500.00" } ], "tax_rows": [ { "name": "IGST@18%", "percentage": "18.00", "applicable_on": "1500.00" } ], "new_customer": { "customer_code": "", "customer_name": "", "email": "", "mobile": "", "address": "", "city": "", "state": "", "zipcode": "", "custom_fields": [ { "id": "845", "name": "GST", "type": "gst", "value": "" } ] } } }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Settle invoice `POST` `/api/v2/merchant/invoice/settle` This endpoint allows you to settle invoice with transaction details #### Request Body | Name | Type | Description | | -------------------- | ------- | -------------------------------------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | invoice\_id | string | System generated invoice id. | | paid\_date | string | Payment date (in the format YYYY-mm-dd) | | amount | number | Settlement amount. | | mode | string | Payment mode (NEFT,Cheque,Cash,Online) | | bank\_name | string | Bank name of transaction. | | bank\_ref\_no | string | Bank reference number | | cheque\_no | string | Cheque number if mode is Cheque | | cash\_paid\_to | string | Cash receiver name. | | notify | integer | Want to send receipt to customer (1 or 0) | | attach\_invoice\_pdf | integer | Want to attach invoice pdf in email (1 or 0) | {% tabs %} {% tab title="200 Invoice settled successfully. " %} ``` { "reqtime": "2021-03-01 20:21:09", "resptime": "2021-03-01 20:21:09", "srvrsp": { "invoice_id": "R000029148", "code": "12121", "transaction_id": "H000001297", "paid_date": "2021-03-01", "patron_name": "Rohit Sharma", "email_id": "user@swipez.in", "amount": "500.00" }, "errcode": 0, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v2/merchant/invoice/settle' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "invoice_id": "", "paid_date": "2021-03-01", "amount": "500.00", "mode": "Online", "bank_name": "", "bank_ref_no": "8749540", "cheque_no": "", "cash_paid_to": "", "notify": "1" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v2/merchant/invoice/settle', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "invoice_id": "", "paid_date": "2021-03-01", "amount": "500.00", "mode": "Online", "bank_name": "", "bank_ref_no": "8749540", "cheque_no": "", "cash_paid_to": "", "notify": "0" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Get invoice details `POST` `/api/v1/merchant/invoice/detail` This endpoint allows you to get invoice details. #### Request Body | Name | Type | Description | | ------------------- | ------ | ---------------------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | invoice\_id | string | System generated invoice id. | {% tabs %} {% tab title="200 " %} ``` { "reqtime": "2021-03-02 09:40:48", "resptime": "2021-03-02 09:40:49", "srvrsp": { "invoice_id": "R000029148", "invoice_number": "INV-5", "bill_date": "01 Mar 2021", "due_date": "01 Mar 2021", "cycle_name": "Test", "customer_code": "12121", "customer_name": "Rohit Sharma", "email": "user@swipez.in", "mobile": "9999999999", "address": "26/2, Herms paras, near Joggers park,Kalyani nagar", "city": "Delhi", "zipcode": "490014", "state": "Delhi", "narrative": "", "absolute_cost": "590.00", "paid_amount": "0.00", "advance": "0.00", "previous_due": "0.00", "late_fee": "0.00", "franchise_id": "0", "short_url": "https://shr.swipez.in/9vb987", "invoice_status": "Paid offline", "custom_column": [ { "column_name": "Custom column 1", "value": "Custom value" } ], "particular": [ { "item": "Maintenance Charges", "sac_code": "99998", "description": "Test", "total_amount": "500.00" } ], "tax": [ { "tax_name": "CGST@9%", "percentage": "9.00", "applicable_on": "500.00", "amount": "45.00", "narrative": "" }, { "tax_name": "SGST@9%", "percentage": "9.00", "applicable_on": "500.00", "amount": "45.00", "narrative": "" } ] }, "errcode": null, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/invoice/detail' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "invoice_id": "" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/invoice/detail', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "invoice_id": "" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Invoice list `POST` `/api/v1/merchant/invoice/getlist` This endpoint allows you to get list of invoices. #### Request Body | Name | Type | Description | | ------------------- | ------ | -------------------------------------------------------------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | from\_date | string | From date (in the format YYYY-mm-dd) from which you want the data. | | to\_date | string | To Date till you want the data | | filter\_by | string | Filter by date type (bill\_date,due\_date,sent\_date) | | invoice\_status | string | Filter by invoice status (Submitted,Failed,Paid online,Paid offline) | | customer\_code | string | Filter by customer code. | | group | string | Filter by customer group. | | franchise\_id | string | Filter by franchise. | {% tabs %} {% tab title="200 Invoices successfully retrieved." %} ``` { "reqtime": "2021-03-02 10:09:15", "resptime": "2021-03-02 10:09:15", "total_records": 2, "srvrsp": [ { "invoice_id": "R000029148", "invoice_number": null, "bill_date": "2021-03-01", "due_date": "2021-03-01", "sent_date": "2021-03-01 18:59:41", "customer_code": "12121", "customer_name": "Rohit Sharma ", "customer_group": "All,Cricket", "email": "rohit@swipez.in", "mobile": "9999999999", "address": "26/2, Herms paras, near Joggers park,Kalyani nagar", "city": "Mumbai", "state": "Maharashtra", "zipcode": "400214", "amount": "590.00", "paid_amount": "0.00", "status": "Paid offline", "cycle_name": "Test", "franchise_id": "0", "franchise_name": null, "created_by": "Test company" }, { "invoice_id": "R000029147", "invoice_number": "INV655", "bill_date": "2021-02-15", "due_date": "2021-02-15", "sent_date": "2021-02-15 16:36:01", "customer_code": "C000359", "customer_name": "Virat Kohli", "customer_group": "All", "email": "virat@swipez.in", "mobile": "9999999998", "address": "", "city": "Delhi", "state": "Delhi", "zipcode": "400014", "amount": "826.00", "paid_amount": "0.00", "status": "Paid offline", "cycle_name": "Test Fee", "franchise_id": "0", "franchise_name": null, "created_by": "Test company" } ], "errcode": null, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/invoice/getlist' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "from_date": "2021-02-04", "to_date": "2021-03-03", "filter_by": "bill_date", "invoice_status": "", "customer_code": "", "group": "", "franchise_id": "" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/invoice/getlist', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "from_date": "2021-02-04", "to_date": "2021-03-03", "filter_by": "bill_date", "invoice_status": "", "customer_code": "", "group": "", "franchise_id": "" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Save subscription `POST` `/api/v1/merchant/subscription/save` This endpoint allows you to save recurring invoicing. #### Request Body | Name | Type | Description | | ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_key\_id | string | Your access key | | secret\_access\_key | string | Your secret key. | | template\_id | string | Invoice format encrypted key. | | mode | string | Recurring mode (Monthly, Daily, Weekly, Yearly) | | repeat\_every | number | Repeat every recurring mode eg. 3 Months | | start\_date | string | Start date of invoice creation | | due\_date | string | Due date of first invoice. | | end\_mode | string |

Recurring stop mode
Never: It will be infinite
Occurences: After occurrence subscription will end
End date: Set end date to stop subscription

| | occurences | number | Set occurrence value if end mode is Occurrences | | end\_date | string | Set end date if end mode is "End date" | | carry\_forword\_dues | string | If you want to carry forward due of unpaid invoices | | invoice | string | Invoice data. | | customer\_code | string | Customer identifier. | | bill\_cycle\_name | string | Billing cycle name eg. Feb 21 | | bill\_date | string | Bill date (in the format of YYYY-mm-dd) | | notify\_patron | number | Invoice notification to customer, 1 for enable | | custom\_header\_fields | string | If you added custom fields in your invoice format you can set value for that column. | | particular\_rows | string | Set values for particular rows as per your invoice format like Item name, Description, Cost | | tax\_rows | string | Add taxes to invoice. | | new\_customer | string | If customer does not exist in Swipez then you can add customer details. | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/subscription/save' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "template_id": "", "mode": "Monthly", "repeat_every": "3", "start_date": "2021-03-01", "due_date": "2021-03-07", "end_mode": "Never", "occurences": "", "end_date": "", "carry_forword_dues": "0", "invoice": { "customer_code": "Cust-1", "bill_cycle_name": "Feb 21", "bill_date": "2021-02-01", "due_date": "2021-02-05", "invoice_properties": { "notify_patron": "1" }, "custom_header_fields": [ { "id": "1853191", "name": "Invoice no", "type": "text", "value": "INV-5" } ], "particular_rows": [ { "item": "Product name", "sac_code": "9899", "description": "Product description", "gst": "18", "total_amount": "1500.00" } ], "tax_rows": [ { "name": "IGST@18%", "percentage": "18.00", "applicable_on": "1500.00" } ], "new_customer": { "customer_code": "", "customer_name": "", "email": "", "mobile": "", "address": "", "city": "", "state": "", "zipcode": "", "custom_fields": [ { "id": "845", "name": "GST", "type": "gst", "value": "" } ] } } }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/subscription/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "template_id": "", "mode": "Monthly", "repeat_every": "3", "start_date": "2021-03-01", "due_date": "2021-03-07", "end_mode": "Never", "occurences": "", "end_date": "", "carry_forword_dues": "0", "invoice": { "customer_code": "Cust-1", "bill_cycle_name": "Feb 21", "bill_date": "2021-02-01", "due_date": "2021-02-05", "invoice_properties": { "notify_patron": "1" }, "custom_header_fields": [ { "id": "1853191", "name": "Invoice no", "type": "text", "value": "INV-5" } ], "particular_rows": [ { "item": "Product name", "sac_code": "9899", "description": "Product description", "gst": "18", "total_amount": "1500.00" } ], "tax_rows": [ { "name": "IGST@18%", "percentage": "18.00", "applicable_on": "1500.00" } ], "new_customer": { "customer_code": "", "customer_name": "", "email": "", "mobile": "", "address": "", "city": "", "state": "", "zipcode": "", "custom_fields": [ { "id": "845", "name": "GST", "type": "gst", "value": "" } ] } } }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Delete invoice `POST` `/api/v3/merchant/invoice/deleteInvoice` This endpoint allows you to delete or cancel the invoice. #### Request Body | Name | Type | Description | | ----------------------------------------------------- | ------ | ---------------------------------------------------------------- | | access\_key\_id\* | String | Your access key | | secret\_access\_key\* | String | Your secret key. | | invoice\_id\* | String | System generated invoice id. | | status\* | String |

Filter by invoice status

(12-cancelled, 13-deleted)

| {% tabs %} {% tab title="200: OK " %} ```javascript { "reqtime": "2022-02-25 18:59:19", "resptime": "2022-02-25 18:59:19", "srvrsp": { "invoice_id": "R000030213" }, "errcode": 0, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} **Sample Code** {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v3/merchant/invoice/deleteInvoice' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "invoice_id": "", "status": "12" //12 cancelled, 13 deleteted }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v3/merchant/invoice/deleteInvoice', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "invoice_id": "", "status": "12" //12 cancelled, 13 deleteted }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} # Customer management Learn more about customer management APIs and their usage. ### Guidelines Below are some of the points you must be aware of while calling Swipez APIs:‌ * All API responses are in JSON format. * POST requests should include `ContentType: application/json` * All API response have **status, message,** and **data**. * Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey). ### Rate limiting The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change. ‌ ### Quick Reference | URL | HTTP Verb | Functionality | | ---------------------------------------------------------------------------------------------- | --------- | --------------------------- | | [/api/v1/merchant/customer/save](https://docs.swipez.in/customer-management#create-customer) | POST | To create customers. | | [/api/v1/merchant/customer/update](https://docs.swipez.in/customer-management#update-customer) | POST | To update created customer. | | [/api/v1/merchant/customer/detail](https://docs.swipez.in/customer-management#customer-detail) | POST | To get customer details. | | [/api/v1/merchant/customer/getlist](https://docs.swipez.in/customer-management#customer-list) | POST | To get customer list. | ## Create customer `POST` `/api/v1/merchant/customer/save` This endpoint allows you to add your customers.\ \ **Download customer format JSON with below steps.** \ 1\. Go to customer structure \ 2\. Click on "Download JSON" button. \ 3\. Choose "Save Customer V1" option. #### Request Body | Name | Type | Description | | ------------------- | ------ | ------------------------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | customer\_code | string | Your customer unique identifier | | customer\_name | string | Customer name | | email | string | Customer email id. | | mobile | string | Customer mobile number. | | address | string | Customer address. | | city | string | Customer city. | | state | string | Customer state. | | zipcode | string | Customer pincode | | custom\_fields | array | Customer custom column value | {% tabs %} {% tab title="200 Customer saved successfully" %} ``` { "reqtime": "2021-03-02 11:34:24", "resptime": "2021-03-02 11:34:25", "srvrsp": [ [ { "customer_id": "13059", "customer_code": "C000360", "customer_name": "Test Customer", "email": "user@swipez.in" } ] ], "errcode": 0, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/customer/save' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "customer": [ { "customer_code": "Cust-254", "customer_name": "Rohit Sharma", "email": "user@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Kolkata", "state": " West Bengal", "zipcode": "700034", "custom_fields": [ { "id": "4839", "name": "Customer GSTN", "type": "gst", "value": "33BRSPP2039T1ZU" }, { "id": "4840", "name": "Company Name", "type": "company_name", "value": "Swipez" } ] } ] }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/customer/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "customer": [ { "customer_code": "Cust-254", "customer_name": "Rohit Sharma", "email": "user@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Kolkata", "state": "West Bengal", "zipcode": "700034", "custom_fields": [ { "id": "4839", "name": "Customer GSTN", "type": "gst", "value": "33BRSPP2039T1ZU" } ] } ] }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'Cookie: __cfduid=d4b581ca97b6435b558bd41f9610f82b51614605091; PHPSESSID=h0md9koeohb4t9tpseem501oua' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Update customer `POST` `/api/v1/merchant/customer/update` This endpoint allows you to update your customer data.\ \ **Download customer format JSON with below steps.** \ 1\. Go to customer structure \ 2\. Click on "Download JSON" button. \ 3\. Choose "Update Customer V1" option. #### Request Body | Name | Type | Description | | ------------------- | ------- | ----------------------------- | | access\_key\_id | string | Your access key | | secret\_access\_key | string | Your secret key. | | customer\_id | integer | System generated customer id. | | customer\_code | string | Customer unique identifier. | | customer\_name | string | Customer name. | | email | string | Customer email id. | | mobile | string | Customer mobile number. | | address | string | Customer address. | | city | string | Customer city. | | state | string | Customer state. | | zipcode | string | Customer zipcode. | | custom\_fields | string | Customer custom column value. | {% tabs %} {% tab title="200 Customer updated successfully." %} ``` { "reqtime": "2021-03-02 11:34:24", "resptime": "2021-03-02 11:34:25", "srvrsp": [ [ { "customer_id": "13059", "customer_code": "C000360", "customer_name": "Test Customer", "email": "user@swipez.in" } ] ], "errcode": 0, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/customer/update' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "customer": [ { "customer_id": "125484", "customer_code": "Cust-254", "customer_name": "Rohit Sharma", "email": "user@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Kolkata", "state": " West Bengal", "zipcode": "700034", "custom_fields": [ { "id": "4839", "name": "Customer GSTN", "type": "gst", "value": "33BRSPP2039T1ZU" }, { "id": "4840", "name": "Company Name", "type": "company_name", "value": "Swipez" } ] } ] }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/customer/update', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "customer": [ { "customer_id": "125484", "customer_code": "Cust-254", "customer_name": "Rohit Sharma", "email": "user@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Kolkata", "state": "West Bengal", "zipcode": "700034", "custom_fields": [ { "id": "4839", "name": "Customer GSTN", "type": "gst", "value": "33BRSPP2039T1ZU" } ] } ] }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'Cookie: __cfduid=d4b581ca97b6435b558bd41f9610f82b51614605091; PHPSESSID=h0md9koeohb4t9tpseem501oua' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Customer list `POST` `/api/v1/merchant/customer/getlist` This endpoint allows you to get list of invoices. #### Request Body | Name | Type | Description | | ------------------- | ------ | --------------------------------------------------------------------------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | searchby | string | Filter by type (customer\_code, name, email, mobile, city, state, zipcode, group) | | keyword | string | Filter keyword. | {% tabs %} {% tab title="200 Customers successfully retrieved." %} ``` { "reqtime": "2021-03-02 10:09:15", "resptime": "2021-03-02 10:09:15", "total_records": 2, "srvrsp": [ { "invoice_id": "R000029148", "invoice_number": null, "bill_date": "2021-03-01", "due_date": "2021-03-01", "sent_date": "2021-03-01 18:59:41", "customer_code": "12121", "customer_name": "Rohit Sharma ", "customer_group": "All,Cricket", "email": "rohit@swipez.in", "mobile": "9999999999", "address": "26/2, Herms paras, near Joggers park,Kalyani nagar", "city": "Mumbai", "state": "Maharashtra", "zipcode": "400214", "amount": "590.00", "paid_amount": "0.00", "status": "Paid offline", "cycle_name": "Test", "franchise_id": "0", "franchise_name": null, "created_by": "Test company" }, { "invoice_id": "R000029147", "invoice_number": "INV655", "bill_date": "2021-02-15", "due_date": "2021-02-15", "sent_date": "2021-02-15 16:36:01", "customer_code": "C000359", "customer_name": "Virat Kohli", "customer_group": "All", "email": "virat@swipez.in", "mobile": "9999999998", "address": "", "city": "Delhi", "state": "Delhi", "zipcode": "400014", "amount": "826.00", "paid_amount": "0.00", "status": "Paid offline", "cycle_name": "Test Fee", "franchise_id": "0", "franchise_name": null, "created_by": "Test company" } ], "errcode": null, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/customer/getlist' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "searchby": "state", "keyword": "maharashtra" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/customer/getlist', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "searchby": "state", "keyword": "maharashtra" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Customer detail `POST` `/api/v1/merchant/customer/detail` This endpoint allows you to get detail of customer. #### Request Body | Name | Type | Description | | ------------------- | ------ | ---------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | customer\_code | string | Customer code | {% tabs %} {% tab title="200 " %} ``` { "reqtime": "2021-03-02 10:09:15", "resptime": "2021-03-02 10:09:15", "total_records": 2, "srvrsp": [ { "invoice_id": "R000029148", "invoice_number": null, "bill_date": "2021-03-01", "due_date": "2021-03-01", "sent_date": "2021-03-01 18:59:41", "customer_code": "12121", "customer_name": "Rohit Sharma ", "customer_group": "All,Cricket", "email": "rohit@swipez.in", "mobile": "9999999999", "address": "26/2, Herms paras, near Joggers park,Kalyani nagar", "city": "Mumbai", "state": "Maharashtra", "zipcode": "400214", "amount": "590.00", "paid_amount": "0.00", "status": "Paid offline", "cycle_name": "Test", "franchise_id": "0", "franchise_name": null, "created_by": "Test company" }, { "invoice_id": "R000029147", "invoice_number": "INV655", "bill_date": "2021-02-15", "due_date": "2021-02-15", "sent_date": "2021-02-15 16:36:01", "customer_code": "C000359", "customer_name": "Virat Kohli", "customer_group": "All", "email": "virat@swipez.in", "mobile": "9999999998", "address": "", "city": "Delhi", "state": "Delhi", "zipcode": "400014", "amount": "826.00", "paid_amount": "0.00", "status": "Paid offline", "cycle_name": "Test Fee", "franchise_id": "0", "franchise_name": null, "created_by": "Test company" } ], "errcode": null, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/customer/detail' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "customer_code": "cust-1" " }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/customer/detail', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "customer_code": "cust-1" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} # Payment gateway Learn more about payment collection APIs and their usage. * [Web integration ](https://docs.swipez.in/payment-gateway/web-integration) * [Payment API](https://docs.swipez.in/payment-gateway/payment-api) # Web integration ## Checkout Payment Form integrates Swipez Payment Gateway in your website to accept payments quickly. In this integration method, you prepare the checkout form with the correct order and payee details and redirect the payee from your checkout page to the payment screen. The Checkout form provides payees with a streamlined flow for initiating payments. Payee enters payment details on the payment screen and completes the payment. Steps to integrate with Swipez Payment Gateway, 1. [​Create Checkout Form](https://docs.swipez.in/web-integration#step-1-create-checkout-form)​ 2. ​[Generate Secure hash](https://docs.swipez.in/web-integration#step-2-generate-signature)​ 3. [​Handle response​](https://docs.swipez.in/web-integration#response-verification) ## Step 1: Create Checkout Form Customers transactions are associated with a unique identifier reference no for each transaction. The transaction amount is associated with an identifier transaction amount. To process the payments for these transactions, you must send us the reference no and the corresponding transaction amount. We send you the payment status against each transaction. You need to send us a few more details to process the payment. Click [here](https://docs.swipez.in/web-integration#request-parameters) to see all the Request Parameters. See the code below on how to generate a valid signature for Checkout integration. Create a sample HTML form like shown below. Ensure to fill in the correct credentials for account id and secret key. You will get account id and xway key from Swipez support. For **Production/Live Environment** set the action attribute of the form to: [https://www.swipez.in/xway/secure​](https://www.swipez.in/xway/secure) For **Test Environment** set the action attribute to: ```markup
``` #### Request Parameters Payment form accepts all the request parameters mentioned below. Ensure you send us all the required fields. Requests with an invalid secure hash will be rejected. | **Parameter** | **Required** | **Description** | | ------------- | ------------ | -------------------------------------------------------------------------- | | account\_id | Yes | Your account ID | | return\_url | Yes | The URL to which the user must be redirected after completing the payment. | | reference\_no | Yes | Your unique transaction reference number. | | amount | Yes | Transaction amount. | | description | No | Transaction description for your reference. | | name | Yes | Name of the payee. | | phone | Yes | Mobile number of the payee. | | email | Yes | Email ID of the payee. | | address | No | Address of payee. | | city | No | City of payee. | | state | No | State of payee. | | postal\_code | No | Zipcode of payee. | | udf1 | No | Extra custom parameter. | | udf2 | No | Extra custom parameter. | | udf3 | No | Extra custom parameter. | | udf4 | No | Extra custom parameter. | | udf5 | No | Extra custom parameter. | | secure\_hash | Yes | Request secure\_hash. | ## Step 2: Generate secure hash Every request to Swipez must contain authentication information to establish the identity of the user making the request. We use a digital signature to validate each transaction. This will ensure integrity of the signed data against tampering. In the sample form above, generate a secure hash for every checkout. The signature is generated as the HMAC value of the data being passed which is using MD5 hash function in combination with your xway key. We will generate a secure hash at our end and want you to do the same with the posted data and match it with the passed argument. > Secure hash generation varies across integration methods, ensure you are using the right secure hash generation method. {% tabs %} {% tab title="PHP" %} ``` $xwaykey=; $account_id=; $amount=1000.00; $reference_no=1234; $return_url=; $hash = $xwaykey."|".$account_id."|".$amount."|".$reference_no."|".$return_url; $secure_hash = md5($hash); ``` {% endtab %} {% tab title="PYTHON" %} ``` import hashlib import hmac import base64 xwaykey= account_id= amount=1000.00 reference_no=1234 return_url= signatureData = xwaykey+"|"+account_id+"|"+amount+"|"+reference_no+"|"+return_url result = hashlib.md5(signatureData.encode()) signature = result.hexdigest() ``` {% endtab %} {% tab title="ASP .NET" %} ``` xwaykey= account_id= amount=1000.00 reference_no=1234 return_url= signatureData = xwaykey+"|"+account_id+"|"+amount+"|"+reference_no+"|"+return_url secure_hash = CreateMD5(signatureData).ToLower(); ``` {% endtab %} {% endtabs %} ## Webhook Notification Webhooks are events that notify you about the payment. A notification is sent to your backend from Swipez when payments are successful. These notifications are useful in cases when the internet connection is unstable or slow while the payment is being processed. This will allow you to reconcile all the successful orders at your end. > * Notifications are sent only for successful payments. > * Sometimes you may receive the same notification more than once. It is recommended to ensure that your implementation of the webhook is idempotent. ## Response Parameters Swipez sends details about every transaction to **return Url**. These parameters will be posted to the services you host on these URLs. The return Url is the webpage where your customer will be redirected to after completing the payment on the Swipez payment page, we will post the response parameters to this page. The response parameters which Swipez posts to these URLs are available below: | Parameter | Description | | --------------------- | --------------------------------------------------------------------------- | | reference\_no | Your transaction reference number for which transaction has been processed. | | amount | Transaction amount. | | request\_amount | Your requested amount. | | transaction\_id | Swipez generated unique transaction ID. Example, X000054545 | | bank\_ref\_no | Bank reference number. | | status | Payment transaction status eg. success or failed. | | mode | Payment mode eg. CREDIT\_*CARD, DEBIT\_CARD, NET\_*BANKING | | date | Transaction date eg. 2021-01-03 11:42:13 | | message | Transaction message. eg. Transaction Successful. | | billing\_name | Payee name. | | billing\_email | Payee email id. | | billing\_mobile | Payee mobile number. | | billing\_address | Payee address. | | billing\_city | Payee city. | | billing\_state | Payee state. | | billing\_postal\_code | Payee pincode. | | udf1 | Extra custom parameter. | | udf2 | Extra custom parameter. | | udf3 | Extra custom parameter. | | udf4 | Extra custom parameter. | | udf5 | Extra custom parameter. | | checksum | Response checksum to validate response. | ## Response Verification Similar to every request signature, we send a digital signature in our response message. We recommend you verify this response signature to check the authenticity of the transaction response. This will ensure that the response has not tampered.PHP PYTHON ASP .NET {% tabs %} {% tab title="PHP" %} ```markup $xwaykey=; $amount=; $reference_no=; $billing_email=; $hash = $xwaykey."|".$amount."|".$reference_no."|".$billing_email; $cecksum= md5($hash); ``` {% endtab %} {% tab title="PYTHON" %} ```markup import hashlib import hmac import base64 xwaykey= amount= reference_no= biiling_email= signatureData = xwaykey+"|"+amount+"|"+reference_no+"|"+biiling_email result = hashlib.md5(signatureData.encode()) signature = result.hexdigest() ``` {% endtab %} {% tab title="ASP .NET" %} ``` xwaykey= amount= reference_no= biiling_email= signatureData = xwaykey+"|"+amount+"|"+reference_no+"|"+biiling_email checksum = CreateMD5(signatureData).ToLower(); ``` {% endtab %} {% endtabs %} ## Integration Kits The integration kits for all major platforms are available below: | Platform | Link | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PHP | [https://drive.google.com/file/d/1ffeFLckIQ6pJFryFOV0XQd08GLBVIf9Z/view](https://drive.google.com/file/d/1ffeFLckIQ6pJFryFOV0XQd08GLBVIf9Z/view?usp=sharing) | | ASP .NET | [https://drive.google.com/file/d/1bCNxrxtZQ3yUq--VwEtRnX3kfjyRbNmq/view](https://drive.google.com/file/d/1bCNxrxtZQ3yUq--VwEtRnX3kfjyRbNmq/view?usp=sharing) | | Node.js | [https://drive.google.com/file/d/1y\_c4sFmmbPhUnLU\_OzZtAZAk58OQ8eoM/view](https://drive.google.com/file/d/1y_c4sFmmbPhUnLU_OzZtAZAk58OQ8eoM/view?usp=sharing) | | Python | [https://drive.google.com/file/d/1Gzoy9-FOoRdInCNUvK-Gn7CyMiYZcYxe/view](https://drive.google.com/file/d/1Gzoy9-FOoRdInCNUvK-Gn7CyMiYZcYxe/view?usp=sharing) | | Ruby | [https://drive.google.com/file/d/1m\_yYemkwFIHrm\_5vQLAnCLrEcQuKaIDR/view](https://drive.google.com/file/d/1m_yYemkwFIHrm_5vQLAnCLrEcQuKaIDR/view?usp=sharing) | | Magento | [https://drive.google.com/file/d/1STGQxsNyirhqf8JWY5WOjVymH\_cN2YJC/view](https://drive.google.com/file/d/1STGQxsNyirhqf8JWY5WOjVymH_cN2YJC/view?usp=sharing) | | Woo-commerce | [https://drive.google.com/file/d/14JyEUWKmxdfooCmvvJrtVXuw9l5zyJlS/view](https://drive.google.com/file/d/14JyEUWKmxdfooCmvvJrtVXuw9l5zyJlS/view?usp=sharing) | After the integration is complete, you can test the flow of the transaction before you start accepting payments online. You can make a test transaction using the test card details available below. You can verify the payment status using the PG Dashboard, APIs. After completing the test, you can start accepting payments from your customers in real-time. **Card Details** | Card Number | Expiry | CVV | Name | | ------------------- | ------ | --- | ---- | | 4111 1111 1111 1111 | 07/23 | 123 | Test | # Payment API ### Guidelines Below are some of the points you must be aware of while calling Swipez APIs: * All API responses are in JSON format. * POST requests should include `ContentType: application/json` * All API response have **status, message,** and **data**. * Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey). ### Rate limiting The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change. ### Quick Reference | URL | HTTP Verb | Functionality | | -------------------------------------------------------------------------------------------- | --------- | ------------------------------------ | | [/api/v1/merchant/payment/received](https://docs.swipez.in/payment-gateway#payment-received) | POST | To get list of payment transactions. | | [/api/v1/merchant/payment/status](https://docs.swipez.in/payment-gateway#payment-status) | POST | To get status of payment. | ## Payment received `POST` `/api/v1/merchant/payment/received` This endpoint allows you to get list of payment transactions. #### Request Body | Name | Type | Description | | ------------------- | ------ | ------------------------------------------------------------------ | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | from\_date | string | From date (in the format YYYY-mm-dd) from which you want the data. | | to\_date | string | To Date till you want the data | {% tabs %} {% tab title="200 " %} ``` { "reqtime": "2021-03-02 16:44:10", "resptime": "2021-03-02 16:44:10", "srvrsp": [ { "customer_name": "Rohit Sharma", "email": "rohit@swipez.in", "code": "cust-1", "transaction_id": "T000002546", "invoice_id": "R000029134", "amount": "472.00", "late_fee": "0.00", "paid_date": "2021-02-05 11:12:12", "payment_mode": "Online Payment" }, { "customer_name": "Virat Kohli", "email": "virat@swipez.in", "code": "cust-2", "transaction_id": "T000002548", "invoice_id": "R000029146", "amount": "472.00", "late_fee": "0.00", "paid_date": "2021-02-15 16:35:01", "payment_mode": "Online Payment" } ], "errcode": null, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/payment/received' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "from_date": "2021-02-04", "to_date": "2021-03-03" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/payment/received', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "from_date": "2021-02-04", "to_date": "2021-03-03", }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Payment status `POST` `/api/v1/merchant/payment/status` This endpoint allows you to get status of payment transaction. #### Request Body | Name | Type | Description | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | | transaction\_type | string |

Transaction type
MERCHANT\_TRANS\_ID : Merchant reference no.
SWIPEZ\_TRANS\_ID: Swipez transaction ID.
SWIPEZ\_REQ\_ID: Swipez invoice id.

| | id | string | Value for transaction type | {% tabs %} {% tab title="200 To get payment transaction status." %} ``` { "reqtime": "2021-03-02 17:03:05", "resptime": "2021-03-02 17:03:05", "srvrsp": { "transaction_id": "X000087677", "reference_no": "1694SZ", "status": "success", "date": "2021-01-21 18:44:23", "bank_ref_no": "8548787", "mode": "NET_BANKING", "amount": "1000.00", "billing_name": "Rohit Sharma", "billing_email": "rohit@swipez.in", "billing_mobile": "9999999999", "billing_address": "Behala Manton Super Market, Room 43, Behala", "billing_city": "Kolkata", "billing_state": "West Bengal", "billing_postal_code": "84587", "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "" }, "errcode": null, "errmsg": "", "errlist": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ``` curl --location --request POST '/api/v1/merchant/payment/status' \ --header 'Content-Type: application/json' \ --data-raw '{ "access_key_id": "", "secret_access_key": "", "transaction_type": "SWIPEZ_TRANS_ID", "id": "X000028783" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/merchant/payment/status', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "access_key_id": "", "secret_access_key": "", "transaction_type": "SWIPEZ_TRANS_ID", "id": "X000028783" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} # Payouts Learn more about payouts APIs and their usage. ### Guidelines Below are some of the points you must be aware of while calling Payouts APIs: * All API requests and responses are in JSON format. * POST requests should include `ContentType: application/json` * All API response have **status, message,** and **data**. * Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey). ### Quick Reference | URL | HTTP Verb | Functionality | | ----------------------------------------------------------------------------------------------- | --------- | ----------------------------- | | [/api/token](https://docs.swipez.in/payouts#get-token) | POST | To get auth token. | | [/api/v1/beneficiary/save](https://docs.swipez.in/payouts#save-beneficiary) | POST | To save beneficiary details. | | [/api/v1/beneficiary/transfer](https://docs.swipez.in/payouts#transfer-amount) | POST | To transfer amount. | | [/api/v1/payout/withdraw](https://docs.swipez.in/payouts#withdraw-amount) | POST | To withdraw amount. | | [/api/v1/payout/balance](https://docs.swipez.in/payouts#get-balance) | GET | To get nodal balance. | | [/api/v1/payout/transferstatus/{type}/{id}](https://docs.swipez.in/payouts#get-transfer-status) | GET | To get transfer status. | | [/api/v1/beneficiary/list](https://docs.swipez.in/payouts#get-beneficiary-list) | GET | To get list of beneficiary. | | [/api/v1/beneficiary/detail](https://docs.swipez.in/payouts#beneficiary-detail) | POST | To fetch beneficiary details. | ### **Authentication** Calling the Authentication APIs allows you to get and verify bearer tokens returned by Swipez. Swipez require these token for all further communication. > * Swipez libraries automatically call the Authorize API and internally store the token. > > * Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used from a different IP address. > > * Token generated is valid for 60 Min . Please ensure that you get a new token by calling the authorize API once the token has expired. ### Rate limiting The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change. ## Get token `POST` `/api/token` This endpoint allows you to get API token. #### Request Body | Name | Type | Description | | ------------------- | ------ | ---------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | {% tabs %} {% tab title="200 " %} ``` { "success": { "token": "" } } ``` {% endtab %} {% tab title="401 " %} ``` { "error": "Invalid Keys", "status": 0 } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/token' \ --form 'access_key_id=""' \ --form 'secret_access_key=""' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/token', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array('access_key_id' => '','secret_access_key' => ''), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Save beneficiary `POST` `/api/v1/beneficiary/save` This endpoint allows you to add beneficiary. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | --------------- | ------ | --------------------- | | name | string | Beneficiary name. | | email\_id | string | Beneficiary email id. | | mobile | string | Beneficiary mobile. | | account\_number | string | Bank account number. | | ifsc | string | Bank IFSC code. | | address | string | Beneficiary address. | | city | string | Beneficiary city. | | state | string | Beneficiary state. | | pincode | string | Beneficiary pincode. | {% tabs %} {% tab title="200 " %} ``` { "success":"Beneficiary added successfully", "status": "1", "beneficiary_id": "8545" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/beneficiary/save' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Rohit Sharma", "email_id": "rohit@swipez.in", "mobile": "9999999999", "account_number": "000111122235", "ifsc": "HDFC0000008", "upi": "rohit@okaxis", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Bangalore", "state": "Karnataka", "pincode": "560001" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/beneficiary/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "name": "Rohit Sharma", "email_id": "rohit@swipez.in", "mobile": "9999999999", "account_number": "000111122235", "ifsc": "HDFC0000008", "upi": "rohit@okaxis", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Bangalore", "state": "Karnataka", "pincode": "560001" }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Transfer amount `POST` `/api/v1/beneficiary/transfer` This endpoint allows you to transfer amount to beneficiary. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | --------------- | ------- | -------------------------------- | | beneficiary\_id | string | System generated beneficiary id. | | amount | integer | Transfer amount. | | reference\_id | string | Your unique reference id. | | narrative | string | Narrative for transaction. | {% tabs %} {% tab title="200 " %} ``` { "success":"Amount transfred successfully", "status": "1", "transfer_status": "SUCCESS", // SUCCESS or PENDING "utr_number": "UTR87542455" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/beneficiary/transfer' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "beneficiary_id":"", "amount": "100", "reference_id": "124", "mode" : "banktransfer", //banktransfer or upi "narrative": "First transfer" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/beneficiary/transfer', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "beneficiary_id":"", "amount": "100", "reference_id": "124", "mode" : "banktransfer", //banktransfer or upi "narrative": "First transfer" }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Withdraw amount `POST` `/api/v1/payout/withdraw` This endpoint allows you to withdraw amount to your bank account from nodal. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | --------- | ------- | ----------------------------------- | | amount | integer | Withdraw amount. | | narrative | string | Narrative for withdraw transaction. | {% tabs %} {% tab title="200 " %} ``` { "success":"Amount withdraw successfully", "status": "1", } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/payout/withdraw' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "100", "narrative": "First withdraw" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/payout/withdraw', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "amount": "100", "narrative": "First withdraw" }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Get balance `GET` `/api/v1/payout/balance` This endpoint allows you to get the ledger balance and available balance of your account. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "balance":"10000.00", "status": "1", } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request GET '/api/v1/payout/balance' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/payout/balance', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', , CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Get transfer status `GET` `/api/v1/payout/transferstatus/{type}/{id}` This endpoint allows you to status of transaction. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string |

Id type (transferid/referenceid)
transferid: Transfer id which is return while transfer amount.
referenceid: Reference id which is sent by merchant while transfer

| | id | number | Reference id or transfer id as per mentioned type. | #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "status": "1", "success": { "transfer": { "referenceId": 17073, "bankAccount": "1212114454", "beneId": "54121", "amount": "100.00", "status": "SUCCESS", "utr": "HGFD542121", "addedOn": "2021-02-01 11:20:00", "processedOn": "2021-02-01 11:20:00", "acknowledged": 1 } } } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/payout/transferstatus/{type}/{id}', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', , CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Get beneficiary list `GET` `/api/v1/beneficiary/list` This endpoint allows you to fetch list of beneficiary. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "success": [ { "beneficiary_id": "V00000010", "merchant_id": "M000054545", "type": "Vendor", "name": "Rohit Sharma", "email_id": "rohit@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Bangalore", "state": "Karnataka", "zipcode": "410014", "bank_account_no": "000111122234", "ifsc_code": "SBIN0009302", "created_date": "2020-02-07 18:53:42" }, { "beneficiary_id": "V00000011", "merchant_id": "M000054545", "type": "Vendor", "name": "Virat Kohli", "email_id": "virat@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Bangalore", "state": "Karnataka", "zipcode": "410014", "bank_account_no": "000111122235", "ifsc_code": "SBIN0009302", "created_date": "2020-02-07 18:53:42" } ], "status": "1" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request GET '/api/v1/beneficiary/list' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/beneficiary/list', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', , CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Beneficiary detail `POST` `/api/v1/beneficiary/detail` This endpoint allows you to fetch beneficiary details. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | --------------- | ------- | -------------- | | account\_number | integer | Account number | | ifsc | string | IFSC code | {% tabs %} {% tab title="200 " %} ``` { "success": { "beneficiary_id": "V00000010", "merchant_id": "M000054545", "type": "Vendor", "name": "Rohit Sharma", "email_id": "rohit@swipez.in", "mobile": "9999999999", "address": "Behala Manton Super Market, Room 43, Behala", "city": "Bangalore", "state": "Karnataka", "zipcode": "410014", "bank_account_no": "000111122234", "ifsc_code": "SBIN0009302", "created_date": "2020-02-07 18:53:42" }, "status": "1" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/beneficiary/detail' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "account_number": "0000122121", "ifsc": "KKBK0001245" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/beneficiary/detail', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "account_number": "0000122121", "ifsc": "KKBK0001245" }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} # E-Invoice Learn more about payouts APIs and their usage. ### If supply is made through E-Commerce then GSTIN of E-Commerce operator can be mentioned hereGuidelines Below are some of the points you must be aware of while calling Payouts APIs: * All API requests and responses are in JSON format. * POST requests should include `ContentType: application/json` * All API response have **status, message,** and **data**. * Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey). ### Quick Refer ### **Authentication** Calling the Authentication APIs allows you to get and verify bearer tokens returned by Swipez. Swipez require these token for all further communication. > * Swipez libraries automatically call the Authorize API and internally store the token. > > * Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used from a different IP address. > > * Token generated is valid for 60 Min . Please ensure that you get a new token by calling the authorize API once the token has expired. ### Rate limiting The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change. ## Get token `POST` `/api/token` This endpoint allows you to get API token. #### Request Body | Name | Type | Description | | ------------------- | ------ | ---------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | {% tabs %} {% tab title="200 " %} ``` { "success": { "token": "" } } ``` {% endtab %} {% tab title="401 " %} ``` { "error": "Invalid Keys", "status": 0 } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/token' \ --form 'access_key_id=""' \ --form 'secret_access_key=""' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/token', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array('access_key_id' => '','secret_access_key' => ''), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Save E-invoice `POST` `/api/v1/einvoice/save` This endpoint allows you to add E-invoice. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | userGstin\* | String | GSTIN of the entity initiating E-Invoice | | pobCode | String |

"This field represents the POB Name for which the user has been given access to initiate any E-Invoice operation.

In case of einvoice, if a POB has been added then, the user has to provide POB in this column. However if POB has not been added, then POB field will be blank"

| | supplyType\* | String | Type of supply whether it is outward/inward. Inward supply is allowed only for E-way bill generation purposes | | ntr\* | String | Nature of transaction i.e. whether Inter/Intra | | docType\* | String | "Type of documents. RI - Regular Invoice (Tax Invoice) C - Credit Note D - Debit Note BS - Bill of Supply BOE - Bill of Entry DC - Delivery Challan OTH - Others" | | catg\* | String | "B2B - Regular B2B Invoices of registered counterparty B2CL - Regular B2CL invoices (Interstate supplies to unregistered dealers or consumers>2.5 lakhs) B2CS - Other than B2CL (unregistered counterparty and consumers) SEWOP – SEZ exports without payment SEWP – SEZ Exports with payment DE – Deemed Exports EXWP - Export with payment of duty EXWOP - Export without payment of duty IMG - Import of Goods OTH - Others" | | dst\* | String | "Status of Document if O - Original, R -Revised" | | trnTyp\* | String | Type of transaction is required to identify the type of movement of goods. Whether it is Regular movement or "Bill to - Ship To" movement or "Bill From - Dispatch From" movement or "Bill To - Ship To and Bill From - Dispatch From" movement. | | no\* | String |

"In case of regular invoice, the invoice number is to be provided. It will be as per invoice number rule mentioned in CGST/SGST rule

Debit/Credit Note number also to be captured here"

| | dt\* | String | In case of regular invoice, this is the invoice date. In case of credit/ debit note, this is date on which the credit / debit note is issued. | | refinum | String | Original Invoice Number in case of Credit / Debit note | | refidt | String | This differential percentage was applicable only till 30th June 2020 and hence it’s a field that is no longer required | | rchrg | String | Whether reverse charge is applicable Y or N | | pos | String | This is place of supply as per rules. Please refer to state codes in Meta Data Codes sheet | | diffprcnt | String | This differential percentage was applicable only till 30th June 2020 and hence it’s a field that is no longer required | | etin | String | | | sgstin | String | "GSTIN of the Supplier. In case user is registered as a normal taxpayer and supply type is outward then this needs to be same as the User GSTIN In case user is registered as a ecommerce operator and supply type is outward then this will be different from User GSTIN whereas In case of inward supplies this can be 15 digit GSTIN or URP in case the supplier is unregistered." | | strdNm | String | Address 1 of the Supplier.(Building/Flat no., Road/Street etc.) | | slglNm | String | Legal Name as appearing in PAN of the Supplier | | sbnm | String | Address 1 of the Supplier.(Building/Flat no., Road/Street etc.) | | sflno | String | "Address 2 of the Supplier(Floor no., Name of the premises/building) " | | sloc | String | Location of the Supplier (City/Town/Village etc.) | | sdst | String | District in which location of supplier is present | | sstcd | String | State code of the state where the location of supplier is present | | spin | String | Pin code of supplier | | sph | String | Phone number/Mobile number of supplier | | sem | String | Email id of supplier | | bgstin | String | GSTIN of Buyer | | btrdNm | String | Trade name of buyerLegal Name as appearing in PAN of the Buyer | | blglNm | String | Legal Name as appearing in PAN of the Buyer | | bbnm | String | Address 1 of the Buyer.(Building/Flat no., Road/Street etc.) | | bflno | String | "Address 2 of the Buyer(Floor no., Name of the premises/building) " | | bloc | String | Location of the Buyer (City/Town/Village etc.) | | bdst | String | District in which location of buyer is present | | bstcd | String | State code of the state where the location of buyer is present | | bpin | String | Pin code of buyer | | bph | String | Phone number/Mobile number of buyer | | bem | String | Email id of buyer | | dgstin | String | GSTIN of the person from where goods are dispatched | | dtrdNm | String | Name of the company from which goods are dispatched. | | dlglNm | String | Legal Name of the entity who dispatch the goods | | dbnm | String | " Address 1 of the entity from which goods are dispatched. (Building/Flat no., Road/Street etc.) " | | dflno | String | "Address 2 of the entity from which goods are dispatched. (Floor no., Name of the premises/building) " | | dloc | String | Location of the entity from which goods are dispatched. | | ddst | String | District of the entity from which goods are dispatched. | | dstcd | String | State code of the entity from which goods are dispatched. | | dpin | String | PIN code of the place of entity from where goods are dispatched. | | dph | String | Phone number/mobile number of the party who dispatch the goods | | dem | String | Email ID of the party who dispatch the goods | | togstin | String | GSTIN of the entity to whom goods are shipped to | | totrdNm | String | Trade name of the entity to whom the supplies are shipped to. | | tolglNm | String | Legal name of the entity to whom the supplies are shipped to. | | tobnm | String | Address1 of the entity to whom the supplies are shipped to. (Building/Flat no., Road/Street etc.) | | toflno | String | Address 2 of the entity to whom the supplies are shipped to. (Floor no., Name of the premises/building) | | toloc | String | Place of entity to whom the supplies are shipped to. (City/Town/Village etc.) | | todst | String | District of the entity to whom goods are shipped to. | | tostcd | String | State code to which the supplies are shipped to. | | topin | String | PIN code of the location to which the supplies are shipped to. | | toph | String | Phone number/Mobile number of the entity to whom goods are shipped to. | | toem | String | Email ID of the entity to whom goods are shipped to. | | sbnum | String | Shipping bill number of the goods exported | | sbdt | String | Shipping bill date of the goods exported | | port | String | Port code of the goods exported | | cntcd | String | Country to which goods are exported, also applicable in case of export of services | | forCur | String | Currency code of the foreign country to which goods/services are exported | | invForCur | String | The total amount of the Invoice in foreign currency | | totinvval | String | The total value of invoice including taxes/GST and rounded to two decimals maximum. This is required to be adjusted for invoice level other charges, discount and round off value provided in the invoice | | totdisc | String | Sum of all discount/rebate/reductions on document level in the Invoice. | | totfrt | String | Freight Charges at Invoice Level | | totins | String | Insurance at Invoice Level | | totothchrg | String | Sum of all other charges on document level in the Invoice. | | totpkg | String | Packaging and Forwarding at Invoice Level | | tottxval | String | Total of assessable / taxable value of all line items of the invoice | | totiamt | String | The IGST amount of all items of the invoice. | | totcamt | String | The CGST amount of all items of the invoice. | | totsamt | String | The SGST amount of all items of the invoice. | | totcsamt | String | This is total cess amount other than State cess including ad valorem as well as non ad valorem | | totstcsamt | String | This is total State cess amount that includes ad valorem as well as non ad valorem | | rndOffAmt | String | This is rounding off amount e.g. 0.21. | | num | String | If an invoice (or a credit/ debit note) has multiple line items, kindly mention a unique serial number for each item, and include the details of each item in a new row separately. If you have only one item, mention Sr. No as 1 | | prdNm | String | Name of the product | | prdDesc | String | Description of Product | | hsnCd | String |

"HSN code is a 4 to 8 digit uniform code that classifies 5000+ products and is accepted worldwide.

For companies having turnover above 5cr for them it is mandatory to provide minimum 6 digit of HSN code."

| | barcde | String | if Bar code is maintained for any product, same can be reported in this field | | qty | String | The quantity of items (goods or services) that is charged in the Invoice line. | | freeQty | String | Detail of any Free of Charge Quantity (FOC) | | unit | String | The unit of measure that applies to the invoiced quantity. | | unitPrice | String | The price of an item, exclusive of GST | | sval | String | (Unit Price \* Quantity) | | disc | String | Discount given on item level | | othchrg | String | Other charges applicable at item level | | txval | String | (Total Amount -Discount) | | rt | String | The GST rate, represented as percentage that applies to each line item of invoice | | irt | String | The IGST rate, represented as percentage that applies to each line item of invoice | | iamt | String | IGST amount applicable to each line item of invoice | | crt | String | The CGST rate, represented as percentage that applies to each line item of invoice | | camt | String | CGST amount applicable to each line item of invoice | | srt | String | The SGST rate, represented as percentage that applies to each line item of invoice | | samt | String | SGST amount applicable to each line item of invoice | | csrt | String | The CESS rate, represented as percentage that applies to each line item of invoice | | csamt | String | CESS amount (advalorem) applicable to each line item of invoice | | itmVal | String | Sum total of all the taxes and taxable value and other charges in single line item : (taxable value + tax amounts+Other charges) | | txp | String | "T - Taxable L - Nil E- Exempt N - Non GST F-Free Supplies" | | bchnm | String | Batch number details if any can be mentioned here | | bchExpDt | String | Expiry date of goods/services can be mentioned here | | bchWrDt | String | Date of warranty of goods can be mentioned here | | isServc | String | Specify whether supply is service or not | | preTaxVal | String | If pre tax value is different from taxable value, mention the pre-tax value and taxable values separately. In some cases the pre-tax value may be different from taxable value. For example, where old goods are exchanged for new ones (e.g. new phone supplied for INR 20,000 along with exchange of old phone - then pre tax value will be 20,000 and taxable value will be 24,000, assuming exchange value of old phone is 4,000. Another example is in the case of real estate where pre-tax value may be different from taxable value). | | ordLineRef | String | Order line reference | | orgCntry | String | This is to specify item origin country like mobile phone sold in India could be manufactured in other country. | | prdSlNo | String | Serial number in case of each item having a unique number. | | attNm | String | Attribute details of the item. | | attVal | String | Attribute value of item. | | itmgen1 | String | Cess Non-Advalorem Rate as required for EWB generation purposes. Allowed values as per Master Codes only. Eg for a product if cess non ad val is 400 per 100, then here value to be inputted in 400. If for some other product it is 4170 per 1000 then value to be inputted is 4170 | | invRmk | String | Any specific remarks with respect to invoice can be entered here | | invStDt | String | Start Date of invoice. | | invEndDt | String | End Date of invoice | | oinum | String | If user wants to provide in a document, a reference to any preceding invoice or debit note or credit note, then this represents the number of such preceding document. Details can be provided in case of amendments | {% tabs %} {% tab title="200 " %} ``` { "status": "SUCCESS", "message": "operation performed successfully", "response": { "qrCode": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAAHfklEQVR42u2ZzYpdOw6FBZoK9CoGTQ1+dYOnBr2KQFODejmQqknT2z1penALAknly8nZlrV+TlH9569J/wD/AP9zIKgdV21kRqm7x5TNk2QQPwJZdqxZp+rmZEVSIt54jHwFuI1GPaibjjZq7p4iIdrsGbA5W3KObhQ7zYelSuZ/AXSOPunw8EkzTgs+Zr7egWqdJKMdoQwOGSvIhfz3HD6AwBn/26/fWXwAVacvvE/tti38tMp0Txm/9+EDiOjFHKxSGrRzZ+M2a6/Nr8Cc1hpr20S8zFaRUt++x3gEanKSci45zmv1Gn0V7xrxCkTf6bPxDt4dL902HrObtPRXwNhkp7bCm7Tk7V5u2ZvxI5Ajcx3ua9tYk+Iok1Yna/oKOLWm4kXlA0PCbc3sXpKvQJ37a7Q9SGeT07bGHrH3ykcgZpdkWYOarD7LT80xVGmsV4Bi4JglMPS1G23D8pym/nMfvoCTBAXBiHV5qxJISC2bxX8P6hOofSBb1LyfPdauKRi9mGjWI5AbM17VaFruNQ/2fqXtye6PwOlpQwmXhqFAwl25t2WunR+BaozvCx6wihIPWx2X3xdk9REIm9CsvaDevsN7c/zpUKnnI1DEXD6Zl3pAEhnfwJUNIn8ETgbEh3FI2NpYtpJjmOP4xiMQuObB1iZmbVY7C+qOLTB7BlbARlaOMSElG54CZ8AI82f9v4DTiAhbay1wZUPp2oG31UgfAbwSVA+WuqO3kNlxTjBG0fJXQEgNV2RBtTBoqVSMDJK4X4HQyZI0ZTSNeXVgYvQsZK9AOW3p5Qoba+JbsPsMfXetZyAi+5jQU45cLWBn/QRgfgROs7C1p2PXRI0Twu7dHdf2EQi60km1ETCwQt36hAiYYJcfgeuJss5ISIjBUXWH5sQ/+3vlPoGYuC2am05DuCmCPa5UHN6PNX8BiWBBLQdm7WdWu3tUUCHq4xXQs/sQOoXDXTTCI7diVn/H/QkgHsmeR1NHZ4Elt4CA5bBhj0DUVX+bPHNKIi36Ysf8ScYjgN1PN+cSSMiEDuMZXaDGP4vzBcDDmuGA98D6FHKmdt/VFGr2CBRWZGXiqh9kTmVFVEw1wUm9Aow5H6SqoQfvdyM8qkKM4c2PAKy5xjhYeTd4opwS3P91qOsjgEQlh/CAO3YsMXae+zSfqx6BgB3waozrJniTQ3rD/d1YQHsFIMVxVoadyRG+kbaQ/hxDfAQON/QGWACUkLE7uUB02Mrvpf0AkJKX04ryawRaAXtyjDsjHwHYQXUlhNTZgkSgQexENslfgYmEgNO+GWvfOz8ROelAkOoRQGzeJrJRwlx5DdgbGgA2IccjEEjpyP+InHNPeMpRvL0DPfwJe1/AuS1sIReUIuxAiF2bFCPAvgLRseuRhOOKWbXmDGVBIxmvwMF9Zxp+s2LPxFH1SoII/ES1L6B0m+OpfKOKwghCkRiPbR31CrTeNZceW2MwRmVXPZri6xFA+RI5yImGJoxCrVhFXB5lW49AtnHPlrCtG730uhNkuTB3fwRCEPZjOuIBDsh7oHtggUXPKwBHmZAeQw8OmMtqtaClm0Z/BhQmAm+1gfy+m1d2CTSC9XOSX0AKmtc5C7EZ4d8Rk/rA+of+leJPIE6cJojKI32F3I8pWKCr80eKPwGBlWn2a9FLW1ojRK6p+xk4fHqnree435iFVuttnrm6PwI4WfLczpDBHjUOBl2CEvFzkl8AHhM2PANHhohxC/VA2Ej/3c0v4BAymqIsEBc6IbRoEly6NeZHACaC1oa4Ng4kfO7ihD+gYEY9Arj3cAL4z58W4R0loi30Kfu1gw8gkKkUjrQGDB4HBXdNwe9RZx6BM+nWSKye0eTWEcQJbRIPm49AIGjGqIG4hhe+jbJQrbtor0fg4M/INZZ4yZ63AzJKxMJ3n4FxkGkUGti0AW3IBvg9gnc+AnEGxjJykKk1ZAMkRcSTDNJXYAdqHNpgawoVYt9XylXWzkfgEOk+affjJk144sDeo0bJ0VfgCmZB+4234Lri5BuURJjqEUCBwk13rIliXxBXYSdYHUzgFUjUwBXoUQJv3RDTPfgK6Z8m9gQcOAgbDBEGciPWWmYJi3wHYk2UHybFlC0w7pOY+i2V/giUjNU7sm4b90MjhoS2NjcCyisQZyKUoUoOJBxp50xDj8t9/tbJTwBn2ife2bSFvypBWMol93n9EcChnH6m3o/fFvLZvE+KBz+/1vwBoAQLShxGnveYeC9ae6v8hL1v4MoH4j+3+8npQBlKONL92ClfARyQKeXqyCl2BVAtMHSIwiNQmDL6XHcUyTX2hhh2Pfh/fz6f/ARuVJwN0udxfz7QBR0ADQAF/xWAIUTClCfGheRPji7FCJA/H6J+AXhZ0on6gFqMcOWwM9sEm/yxgy/gz49I5A4Kd+TGA2gqZg0tWa8A20AgQGVABcFL2/lTphbReAbQXLDzc2ihfqFD4NxHp/xrrA9AD7ofPOLvaKJbIqzVWAgJ4xWAkeLqQ8YIZRRJ834CBSX8/YjjCwjYQJ7pfV0J2zH6xOagBBx7BP75yeA/wP8V8C/LfRb3Y34pFQAAAABJRU5ErkJggg==", "no": "1809961", "id": 51587, "genBy": "amit.nandha@irisbusiness.com", "genByName": "Amit Nandha", "status": "ACT", "ackNo": 112010005963729, "ackDt": "2020-09-19 00:23:00", "irn": "0c3e498d5cb6380ceb2c8fe7a0d27702662bc9742d2d0aa6c11e3daead23362f", "signedInvoice": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkVEQzU3REUxMzU4QjMwMEJBOUY3OTM0MEE2Njk2ODMxRjNDODUwNDciLCJ0eXAiOiJKV1QiLCJ4NXQiOiI3Y1Y5NFRXTE1BdXA5NU5BcG1sb01mUElVRWMifQ.eyJkYXRhIjoie1wiQWNrTm9cIjoxMTIwMTAwMDU5NjM3MjksXCJBY2tEdFwiOlwiMjAyMC0wOS0xOSAwMDoyMzowMFwiLFwiSXJuXCI6XCIwYzNlNDk4ZDVjYjYzODBjZWIyYzhmZTdhMGQyNzcwMjY2MmJjOTc0MmQyZDBhYTZjMTFlM2RhZWFkMjMzNjJmXCIsXCJWZXJzaW9uXCI6XCIxLjAxXCIsXCJUcmFuRHRsc1wiOntcIlRheFNjaFwiOlwiR1NUXCIsXCJTdXBUeXBcIjpcIkIyQlwiLFwiUmVnUmV2XCI6XCJOXCIsXCJJZ3N0T25JbnRyYVwiOlwiTlwifSxcIkRvY0R0bHNcIjp7XCJUeXBcIjpcIklOVlwiLFwiTm9cIjpcIjE4MDk5NjFcIixcIkR0XCI6XCIyOC8wOC8yMDIwXCJ9LFwiU2VsbGVyRHRsc1wiOntcIkdzdGluXCI6XCIyOUFBQUNJOTI2MFIwMDBcIixcIkxnbE5tXCI6XCJOQUhBUlNQR01JTExTTFREKFBMT1QtMzczKVwiLFwiVHJkTm1cIjpcIk5BSEFSU1BHTUlMTFNMVEQoUExPVC0zNzMpXCIsXCJBZGRyMVwiOlwiKFBST1AuTkFIQVJTUEdNSUxMU0xURC4pXCIsXCJBZGRyMlwiOlwiSEVBRE9GRklDRVwiLFwiTG9jXCI6XCJMVURISUFOQVwiLFwiUGluXCI6NTg3MjAxLFwiU3RjZFwiOlwiMjlcIn0sXCJCdXllckR0bHNcIjp7XCJHc3RpblwiOlwiMjNBQUFDTjU3MTBEMVo0XCIsXCJMZ2xObVwiOlwiTkFIQVJTUEdNSUxMU0xURC5VTklULUVYVFwiLFwiVHJkTm1cIjpcIk5BSEFSU1BHTUlMTFNMVEQuVU5JVC1FWFRcIixcIlBvc1wiOlwiMjdcIixcIkFkZHIxXCI6XCJWSUxMU0lNUkFJLE1BTkRJREVFUCxcIixcIkxvY1wiOlwiTUFORElERUVQXCIsXCJQaW5cIjo0NTc4ODcsXCJQaFwiOlwiMDc0ODAyMzMwOTFcIixcIlN0Y2RcIjpcIjIzXCJ9LFwiSXRlbUxpc3RcIjpbe1wiSXRlbU5vXCI6MCxcIlNsTm9cIjpcIjEwXCIsXCJJc1NlcnZjXCI6XCJOXCIsXCJIc25DZFwiOlwiNjMxMFwiLFwiUXR5XCI6MS4wMCxcIkZyZWVRdHlcIjowLjAwMCxcIlVuaXRcIjpcIk5PU1wiLFwiVW5pdFByaWNlXCI6MjUwMDAwLjAwLFwiVG90QW10XCI6MjUwMDAwLjAwLFwiRGlzY291bnRcIjowLjAwLFwiUHJlVGF4VmFsXCI6MC4wMCxcIkFzc0FtdFwiOjI1MDAwMC4wMCxcIkdzdFJ0XCI6MC4wMCxcIklnc3RBbXRcIjowLjAwLFwiQ2dzdEFtdFwiOjAuMDAsXCJTZ3N0QW10XCI6MC4wMCxcIkNlc1J0XCI6MC4wMCxcIkNlc0FtdFwiOjAuMDAsXCJDZXNOb25BZHZsQW10XCI6MC4wMCxcIlN0YXRlQ2VzUnRcIjowLjAwLFwiU3RhdGVDZXNBbXRcIjowLjAwLFwiT3RoQ2hyZ1wiOjAuMDAsXCJUb3RJdGVtVmFsXCI6MjUwMDAwLjAwLFwiQXR0cmliRHRsc1wiOlt7XCJObVwiOlwiMDAwMDEwXCIsXCJWYWxcIjpcIjAuMDBcIn1dfV0sXCJWYWxEdGxzXCI6e1wiQXNzVmFsXCI6MjUwMDAwLjAwLFwiQ2dzdFZhbFwiOjAuMDAsXCJJZ3N0VmFsXCI6MC4wMCxcIkNlc1ZhbFwiOjAuMDAsXCJTdENlc1ZhbFwiOjAuMDAsXCJEaXNjb3VudFwiOjAuMDAsXCJPdGhDaHJnXCI6MC4wMCxcIlJuZE9mZkFtdFwiOjAuMDAsXCJUb3RJbnZWYWxcIjoyNTAwMDAuMDAsXCJUb3RJbnZWYWxGY1wiOjAuMDB9LFwiUGF5RHRsc1wiOntcIkNyRGF5XCI6MCxcIlBhaWRBbXRcIjowLjAwLFwiUGF5bXREdWVcIjowLjAwfSxcIlJlZkR0bHNcIjp7fSxcIkV3YkR0bHNcIjp7XCJUcmFuc0lkXCI6XCIyOUFBQUNJOTI2MFIwMDBcIixcIlRyYW5zTmFtZVwiOlwiQUJDXCIsXCJUcmFuc01vZGVcIjpcIjFcIixcIkRpc3RhbmNlXCI6OTU2LFwiVHJhbnNEb2NOb1wiOlwiMTAyOVwiLFwiVHJhbnNEb2NEdFwiOlwiMjgvMDgvMjAyMFwiLFwiVmVoTm9cIjpcIk1IMDFZVTEyMzRcIixcIlZlaFR5cGVcIjpcIlJcIn19IiwiaXNzIjoiTklDIn0.HilzZ9FaMBOdyQ1mmDiNrZcb7-Zm3vYUaJyHBzMVw258S1QuG11W4aA48q9KV_Ck-0DEmGsJlj37K2klLRfSu5TVZL1RtclkiLvGCIDFVH-AR8VX5pvuGi6gUfPvfcUNn2b9WA7Qiafe63sn2FIQzSTLBXU9hETuN54hlckwOJ0rnkdYLee5m7BjwaGgeEcQnCM4I2CHJuDBy2wj73iERXRTbp_w0vADQCz48huOYNtkULXeL3FbIa3EbNp8fZgKqEV8tmje1oqAvmTRxm89h2OOEALEoBwLxisuydLY_-W3i0osQvmXB57fTfc5o8OGOSa8V-c9JdkwUbnwlKznAw", "signedQrCode": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkVEQzU3REUxMzU4QjMwMEJBOUY3OTM0MEE2Njk2ODMxRjNDODUwNDciLCJ0eXAiOiJKV1QiLCJ4NXQiOiI3Y1Y5NFRXTE1BdXA5NU5BcG1sb01mUElVRWMifQ.eyJkYXRhIjoie1wiU2VsbGVyR3N0aW5cIjpcIjI5QUFBQ0k5MjYwUjAwMFwiLFwiQnV5ZXJHc3RpblwiOlwiMjNBQUFDTjU3MTBEMVo0XCIsXCJEb2NOb1wiOlwiMTgwOTk2MVwiLFwiRG9jVHlwXCI6XCJJTlZcIixcIkRvY0R0XCI6XCIyOC8wOC8yMDIwXCIsXCJUb3RJbnZWYWxcIjoyNTAwMDAuMDAsXCJJdGVtQ250XCI6MSxcIk1haW5Ic25Db2RlXCI6XCI2MzEwXCIsXCJJcm5cIjpcIjBjM2U0OThkNWNiNjM4MGNlYjJjOGZlN2EwZDI3NzAyNjYyYmM5NzQyZDJkMGFhNmMxMWUzZGFlYWQyMzM2MmZcIixcIklybkR0XCI6XCIyMDIwLTA5LTE5IDAwOjIzOjAwXCJ9IiwiaXNzIjoiTklDIn0.szP6ZIees02yz4j4-AIiuTjdiJTYRZPqz9QK4lcZPvx5yY6awP5DG3wn7DuLFA4VMU4KJ4rNN2tv1lSkKM9EHYgCqivj7qCNt9J5KGZAwjSc4RH8MWbUrz3KLvRC_dc5EVGlYqeAsQFdW9DWqf_w8o7PsitwJ8yPaz-KUo07Qr95djEubynB7u7e3crw6t706aPrmRqmCNF-Hne5ZYfe0yQK7xjkWMob9j-G9geCeLUoNwNygFGPnoFvMIm1tk5OAfxTnXSZR1mW14kd8v1eArWlFViZHWmCcngCsnBken5cIUQWW_pPxK3H5_YD2ZzTHn9G9zNaPTslKnhJoG0KWA", "EwbNo": "191008719181", "EwbDt": "2020-09-19 00:24:00", "EwbValidTill": "2020-09-29 23:59:00" } } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/einvoice/save' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "userGstin": "01AAACI9260R002", "pobCode": null, "supplyType": "O", "ntr": "Inter", "docType": "RI", "catg": "B2B", "dst": "O", "trnTyp": "REG", "no": "AG/03-09/4565", "dt": "28-03-2021", "refinum": null, "refidt": null, "pos": "27", "diffprcnt": null, "etin": null, "rchrg": "N", "sgstin": "01AAACI9260R002", "strdNm": "TEST Company", "slglNm": "TEST PROD", "sbnm": "Testing", "sflno": "ABC", "sloc": "BANGALOR32", "sdst": "BENGALURU", "sstcd": "01", "spin": "192233", "sph": "123456111111", "sem": "abc123@gmail.com", "bgstin": "02AAACI9260R002", "btrdNm": "TEST ENTERPRISES", "blglNm": "TEST PRODUCT", "bbnm": "ABCD12345", "bflno": "abc", "bloc": "Jijamat", "bdst": "BANGALORE", "bstcd": "02", "bpin": "174001", "bph": "989898111111", "bem": "abc123@gmail.com", "dgstin": null, "dtrdNm": null, "dlglNm": null, "dbnm": null, "dflno": null, "dloc": null, "ddst": null, "dstcd": null, "dpin": null, "dph": null, "dem": null, "togstin": null, "totrdNm": null, "tolglNm": null, "tobnm": null, "toflno": null, "toloc": null, "todst": null, "tostcd": null, "topin": null, "toph": null, "toem": null, "sbnum": null, "sbdt": null, "port": null, "expduty": 1234, "cntcd": null, "forCur": null, "invForCur": null, "taxSch": "GST", "totinvval": 4262.73, "totdisc": 10, "totfrt": null, "totins": null, "totpkg": null, "totothchrg": 20, "tottxval": 3322.45, "totiamt": 930.28, "totcamt": 0, "totsamt": 0, "totcsamt": 0, "totstcsamt": 0, "rndOffAmt": 0, "sec7act": "N", "invStDt": null, "invEndDt": null, "invRmk": null, "omon": null, "odty": null, "oinvtyp": "B2CL", "octin": null, "userIRN": null, "payNm": null, "acctdet": null, "pa":null, "mode": null, "ifsc": null, "payTerm": null, "payInstr": null, "crTrn": null, "dirDr": null, "crDay": null, "balAmt": null, "paidAmt": null, "payDueDt": null, "transId": null, "subSplyTyp": "Supply", "subSplyDes": null, "kdrefinum": null, "kdrefidt": null, "transMode": null, "vehTyp": null, "transDist": "", "transName": null, "transDocNo": null, "transDocDate": null, "vehNo": null, "clmrfnd": null, "rfndelg": null, "boef": null, "fy": null, "refnum": null, "pdt": null, "ivst": null, "cptycde": null, "gen1": "abcd", "gen2": "abcd", "gen3": "abcd", "gen4": "abcd", "gen5": "abcd", "gen6": "abcd", "gen7": "abcd", "gen8": "abcd", "gen9": "abcd", "gen10": "abcd", "gen11": "abcd", "gen12": "abcd", "gen13": "abcd", "gen14": "PJTCG001", "gen15": "abcd", "gen16": "abcd", "gen17": "abcd", "gen18": "abcd", "gen19": "abcd", "gen20": "abcd", "gen21": "abcd", "gen22": "abcd", "gen23": "abcd", "gen24": "abcd", "gen25": "abcd", "gen26": "abcd", "gen27": "abcd", "gen28": "abcd", "gen29": "abcd", "gen30": "abcd", "pobewb": "Null", "pobret": "Null", "tcsrt": "null", "tcsamt": 0, "pretcs": 0, "genIrn": true, "genewb": "N", "signedDataReq": true, "itemList": [ { "barcde": null, "bchExpDt": null, "bchWrDt": null, "bchnm": null, "camt": 0, "cesNonAdval": 0, "stCesNonAdvl": 0, "crt": 0, "csamt": 0, "csrt": 0, "disc": 0, "freeQty": 0, "hsnCd": "73041190", "iamt": 930.28, "irt": 28, "isServc": null, "itmgen1": null, "itmgen2": null, "itmgen3": null, "itmgen4": null, "itmgen5": null, "itmgen6": null, "itmgen7": null, "itmgen8": null, "itmgen9": null, "itmgen10": null, "itmVal": 4252.73, "num": "00001", "ordLineRef": null, "orgCntry": null, "othchrg": 0, "prdDesc": null, "prdNm": "SEAMLESS STEEL TUBE 10X2 -U71889903", "prdSlNo": null, "preTaxVal": 0, "qty": 1, "rt": 28, "samt": 0, "srt": 0, "stcsamt": 0, "stcsrt": 0, "sval": 3322.45, "txp": null, "txval": 3322.45, "unit": "NOS", "unitPrice": 3322.451, "invItmOtherDtls": [ { "attNm": "aaa", "attVal": "aaa" }, { "attNm": "xyz", "attVal": "2300" } ] } ], "invOthDocDtls": [ { "url": "www.google.com", "docs": "This is the url", "infoDtls": "abcd" } ], "invRefPreDtls": [ { "oinum": null, "oidt": null, "othRefNo": null } ], "invRefContDtls": [ { "raref": null, "radt": null, "tendref": null, "contref": null, "extref": null, "projref": null, "poref": null, "porefdt": null } ] }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/einvoice/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "userGstin": "01AAACI9260R002", "pobCode": null, "supplyType": "O", "ntr": "Inter", "docType": "RI", "catg": "B2B", "dst": "O", "trnTyp": "REG", "no": "AG/03-09/4565", "dt": "28-03-2021", "refinum": null, "refidt": null, "pos": "27", "diffprcnt": null, "etin": null, "rchrg": "N", "sgstin": "01AAACI9260R002", "strdNm": "TEST Company", "slglNm": "TEST PROD", "sbnm": "Testing", "sflno": "ABC", "sloc": "BANGALOR32", "sdst": "BENGALURU", "sstcd": "01", "spin": "192233", "sph": "123456111111", "sem": "abc123@gmail.com", "bgstin": "02AAACI9260R002", "btrdNm": "TEST ENTERPRISES", "blglNm": "TEST PRODUCT", "bbnm": "ABCD12345", "bflno": "abc", "bloc": "Jijamat", "bdst": "BANGALORE", "bstcd": "02", "bpin": "174001", "bph": "989898111111", "bem": "abc123@gmail.com", "dgstin": null, "dtrdNm": null, "dlglNm": null, "dbnm": null, "dflno": null, "dloc": null, "ddst": null, "dstcd": null, "dpin": null, "dph": null, "dem": null, "togstin": null, "totrdNm": null, "tolglNm": null, "tobnm": null, "toflno": null, "toloc": null, "todst": null, "tostcd": null, "topin": null, "toph": null, "toem": null, "sbnum": null, "sbdt": null, "port": null, "expduty": 1234, "cntcd": null, "forCur": null, "invForCur": null, "taxSch": "GST", "totinvval": 4262.73, "totdisc": 10, "totfrt": null, "totins": null, "totpkg": null, "totothchrg": 20, "tottxval": 3322.45, "totiamt": 930.28, "totcamt": 0, "totsamt": 0, "totcsamt": 0, "totstcsamt": 0, "rndOffAmt": 0, "sec7act": "N", "invStDt": null, "invEndDt": null, "invRmk": null, "omon": null, "odty": null, "oinvtyp": "B2CL", "octin": null, "userIRN": null, "payNm": null, "acctdet": null, "pa":null, "mode": null, "ifsc": null, "payTerm": null, "payInstr": null, "crTrn": null, "dirDr": null, "crDay": null, "balAmt": null, "paidAmt": null, "payDueDt": null, "transId": null, "subSplyTyp": "Supply", "subSplyDes": null, "kdrefinum": null, "kdrefidt": null, "transMode": null, "vehTyp": null, "transDist": "", "transName": null, "transDocNo": null, "transDocDate": null, "vehNo": null, "clmrfnd": null, "rfndelg": null, "boef": null, "fy": null, "refnum": null, "pdt": null, "ivst": null, "cptycde": null, "gen1": "abcd", "gen2": "abcd", "gen3": "abcd", "gen4": "abcd", "gen5": "abcd", "gen6": "abcd", "gen7": "abcd", "gen8": "abcd", "gen9": "abcd", "gen10": "abcd", "gen11": "abcd", "gen12": "abcd", "gen13": "abcd", "gen14": "PJTCG001", "gen15": "abcd", "gen16": "abcd", "gen17": "abcd", "gen18": "abcd", "gen19": "abcd", "gen20": "abcd", "gen21": "abcd", "gen22": "abcd", "gen23": "abcd", "gen24": "abcd", "gen25": "abcd", "gen26": "abcd", "gen27": "abcd", "gen28": "abcd", "gen29": "abcd", "gen30": "abcd", "pobewb": "Null", "pobret": "Null", "tcsrt": "null", "tcsamt": 0, "pretcs": 0, "genIrn": true, "genewb": "N", "signedDataReq": true, "itemList": [ { "barcde": null, "bchExpDt": null, "bchWrDt": null, "bchnm": null, "camt": 0, "cesNonAdval": 0, "stCesNonAdvl": 0, "crt": 0, "csamt": 0, "csrt": 0, "disc": 0, "freeQty": 0, "hsnCd": "73041190", "iamt": 930.28, "irt": 28, "isServc": null, "itmgen1": null, "itmgen2": null, "itmgen3": null, "itmgen4": null, "itmgen5": null, "itmgen6": null, "itmgen7": null, "itmgen8": null, "itmgen9": null, "itmgen10": null, "itmVal": 4252.73, "num": "00001", "ordLineRef": null, "orgCntry": null, "othchrg": 0, "prdDesc": null, "prdNm": "SEAMLESS STEEL TUBE 10X2 -U71889903", "prdSlNo": null, "preTaxVal": 0, "qty": 1, "rt": 28, "samt": 0, "srt": 0, "stcsamt": 0, "stcsrt": 0, "sval": 3322.45, "txp": null, "txval": 3322.45, "unit": "NOS", "unitPrice": 3322.451, "invItmOtherDtls": [ { "attNm": "aaa", "attVal": "aaa" }, { "attNm": "xyz", "attVal": "2300" } ] } ], "invOthDocDtls": [ { "url": "www.google.com", "docs": "This is the url", "infoDtls": "abcd" } ], "invRefPreDtls": [ { "oinum": null, "oidt": null, "othRefNo": null } ], "invRefContDtls": [ { "raref": null, "radt": null, "tendref": null, "contref": null, "extref": null, "projref": null, "poref": null, "porefdt": null } ] }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## E-invoice cancel `POST` `/api/v1/einvoice/cancel` This endpoint allows you to cancel invoice. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | {% tabs %} {% tab title="200 " %} ``` {"status":"SUCCESS","message":"operation performed successfully","response":{"irn":"a287f526ec393d69a6202156d285e2e508902dedda1ed3daeadda8a5c2696a6d","cancelDate":"2020-02-06 19:30:00"},"fieldErrors":null,"errors":null} ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/einvoice/cancel' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "irn":"a287f526ec393d69a6202156d285e2e508902dedda1ed3daeadda8a5c2696a6d", "cnlRsn":"1", "cnlRem":"Wrong entry", "userGstin":"01AAACI9260R002" }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/einvoice/cancel', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "irn":"a287f526ec393d69a6202156d285e2e508902dedda1ed3daeadda8a5c2696a6d", "cnlRsn":"1", "cnlRem":"Wrong entry", "userGstin":"01AAACI9260R002" }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## E-invoice list `POST` `/api/v1/einvoice/list` This endpoint allows you to get invoice list. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "status": "SUCCESS", "message": "Einvoices filtered successfully", "response": { "data": [ { "einvId": 371, "docType": "RI", "catg": "B2B", "docNo": "P001", "docDt": "01/01/2020", "bgstin": "33GSPTN0121G1ZP", "btrdNm": "Big basket Ltd", "invStatus": "UPLOADED", "totinvval": 22356, "numItems": 0, "hasError": true, "hasWarning": true } ], "pageNumber": 0, "numberOfElements": 1, "totalElements": 1, "totalPages": 1 }, "fieldErrors": null, "errors": null } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/einvoice/list' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "gstin": "01AAACI9260R002", "docNo": [ "12369" ], "fromDt": "19/02/2020", "toDt": "19/02/2020", "btrdNm": "Aamir Traders", "catg": [ "B2B" ], "docType": [ "RI" ], "invStatus": [ "UPLOADED", "IRN_GENERATED" ], "irnStatus": [ "ACT", "CAN" ], "totinvval": { "gt": "8000" }, "itemCount": { "gt": "0" }, "hasError": false, "hasWarning": true, "page": 0, "size": 50 }' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/einvoice/list', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "gstin": "01AAACI9260R002", "docNo": [ "12369" ], "fromDt": "19/02/2020", "toDt": "19/02/2020", "btrdNm": "Aamir Traders", "catg": [ "B2B" ], "docType": [ "RI" ], "invStatus": [ "UPLOADED", "IRN_GENERATED" ], "irnStatus": [ "ACT", "CAN" ], "totinvval": { "gt": "8000" }, "itemCount": { "gt": "0" }, "hasError": false, "hasWarning": true, "page": 0, "size": 50 }', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Get invoice details `GET` `/api/v1/einvoice/details` This endpoint allows you to get the invoice details. #### Query Parameters | Name | Type | Description | | ---------------------------------------- | ------ | ----------- | | einvId\* | String | | #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | ---- | ------ | ----------- | | | String | | {% tabs %} {% tab title="200 " %} ``` { "status": "SUCCESS", "message": "Einvoice ftched successfully", "response": { "einvId": 332, "supplyType": "O", "docType": "RI", "catg": "B2B", "docNo": "123652", "docDt": "12/05/2019", "trnTyp": "REG", "bgstin": "28AAACG0569P1Z3", "btrdNm": "LAKSHMI ENTERPRISES", "itemList": [ { "prdNm": "WHEAT AND MESLIN", "prdDesc": "WHEAT AND MESLIN", "hsnCd": "1001", "qty": 2, "unit": "BAG", "unitPrice": 100, "sval": 200, "txval": 205, "rt": 18, "iamt": 0, "camt": 0, "samt": 0, "csamt": 1, "stcsamt": 2, "errors": [ { "errorId": 1920, "fieldName": "txval", "type": "ERROR", "description": "If docTyp = RI/BS then Assessable amount/ Taxable amount should be item Total Amount - Discount + Other charges.", "lineItemIdFk": 1196 }, { "errorId": 1921, "fieldName": "rt", "type": "ERROR", "description": "Tax rates and amounts should not be present for Nil exempt and Non-gst supplies.", "lineItemIdFk": 1196 }, { "errorId": 1922, "fieldName": "crt", "type": "ERROR", "description": "CGST rate should not be filled for inter-state transactions.", "lineItemIdFk": 1196 }, { "errorId": 1923, "fieldName": "srt", "type": "ERROR", "description": "SGST rate should not be filled for inter-state transactions.", "lineItemIdFk": 1196 } ], "hasError": false, "hasWarning": false } ], "irnStatus": "ACT", "totinvval": 12400, "hasError": false, "hasWarning": false, "ntr": "INTER", "dst": "O", "rchrg": "Y", "pos": 4, "etin": "37BZNPM9430M1KL", "sgstin": "29ACQPN4602B000", "strdNm": "AMBIKA CEMENTS", "sbno": "1", "sbnm": "AMBIKA CEMENTS", "sflno": "2", "sloc": "BENGALURU", "sdst": "BENGALURU", "sstcd": 29, "spin": 560090, "sph": 9898989898, "sem": "abc123@gmail.com", "bbno": "785", "bbnm": "test", "bflno": "ab", "bloc": "BANGALORE", "bdst": "BANGALORE", "bstcd": 29, "bpin": 560054, "bph": 9898989898, "bem": "abc123@gmail.com", "dstcd": 0, "dpin": 0, "dph": 9898989898, "tostcd": 0, "topin": 0, "toph": 0, "cntcd": "IN", "taxSch": "GST", "tottxval": 10000, "totiamt": 0, "totcamt": 1200, "totsamt": 1200, "totstcsamt": 0, "totcsNonAdVal": 0, "sec7act": "Y", "crDay": 0, "ackNo": 10100041122, "ackDt": "2020-02-05T11:56:00.000+0000", "irn": "fa1a2a58b37173b241f2bea41f97621e125fbd9cd982eed64fc3ae2b4abe95a5" }, "fieldErrors": null, "errors": null } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request GET '/api/v1/einvoice/details?einvId=2133' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/einvoice/details?einvId=2133', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', , CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} #### Sample code # Franchise Learn more about franchise APIs and their usage. ### Guidelines Below are some of the points you must be aware of while calling Payouts APIs: * All API requests and responses are in JSON format. * POST requests should include `ContentType: application/json` * All API response have **status, message,** and **data**. * Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey). ### Quick Reference | URL | HTTP Verb | Functionality | | -------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- | | [/api/token](https://app.gitbook.com/@billing-software/s/swipez-docs/~/drafts/-MdozwnKEnONfPzpH76b/franchise#get-token) | POST | To get auth token. | | [/api/v1/franchise/save](https://app.gitbook.com/@billing-software/s/swipez-docs/franchise#save-franchise) | POST | To save franchise details. | | [/api/v1/franchise/update](https://app.gitbook.com/@billing-software/s/swipez-docs/~/drafts/-MdozwnKEnONfPzpH76b/franchise#update-franchise) | POST | To update franchise details. | | [/api/v1/franchise/delete](https://app.gitbook.com/@billing-software/s/swipez-docs/~/drafts/-MdozwnKEnONfPzpH76b/franchise#delete-franchise) | POST | To delete franchise. | ### **Authentication** Calling the Authentication APIs allows you to get and verify bearer tokens returned by Swipez. Swipez require these token for all further communication. > * Swipez libraries automatically call the Authorize API and internally store the token. > > * Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used from a different IP address. > > * Token generated is valid for 60 Min . Please ensure that you get a new token by calling the authorize API once the token has expired. ### Rate limiting The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change. ## Get token `POST` `/api/token` This endpoint allows you to get API token. #### Request Body | Name | Type | Description | | ------------------- | ------ | ---------------- | | access\_key\_id | string | Your access key. | | secret\_access\_key | string | Your secret key. | {% tabs %} {% tab title="200 " %} ``` { "success": { "token": "" } } ``` {% endtab %} {% tab title="401 " %} ``` { "error": "Invalid Keys", "status": 0 } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/token' \ --form 'access_key_id=""' \ --form 'secret_access_key=""' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/token', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array('access_key_id' => '','secret_access_key' => ''), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Save franchise `POST` `/api/v1/franchise/save` This endpoint allows you to add franchise. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | -------------------------- | ------ | ------------------------------------------------------------------------------ | | franchise\_code | string | Unique identifier | | franchise\_name | string | Name of franchise. | | contact\_person\_name | string | Contact person name. | | email\_id | string | Email id of franchise. | | mobile | string | 10 digit mobile number of franchise | | pan\_number | string | 10 Char Pan number | | aadhar\_number | string | 12 digit Aadhar num | | gst\_number | string | 15 char GST number. | | address | string | Franchise address. | | city | string | Franchise city. | | state | string | Franchise state. | | zipcode | string | Franchise zipcode | | enable\_online\_settlement | number | If you want transfer franchise commission online. Values 1 for yes 0 for no. | | commission\_type | string | Values: Percentage or Fixed | | commission | number | Commission value either amount or percentage | | settlement\_type | string | "Auto" for automatic transfer commission amount. "Manual" for manual transfer. | | bank\_holder\_name | string | Bank account holder name | | account\_number | string | Bank account number | | bank\_name | string | Bank name | | account\_type | string | Account type "Saving" or "Current" | | ifsc | string | IFSC code | | enable\_franchise\_login | string | To enable franchise login 1 for yes 0 for no. | | login\_email | string | Franchise login email id | | password | string | Franchise login password | | role\_name | string | Role name you can find in Setting->Roles menu on web dashboard | | | string | | {% tabs %} {% tab title="200 " %} ``` { "success":"Franchise saved successfully", "status": "1", "franchise_id": "8545" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/franchise/save' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "franchise_code": "5", "franchise_name": "john Ppp", "contact_person_name":"Paresh", "email_id": "johndoe@swipez.in", "mobile": "9999999999", "pan_number": "", "aadhar_number": "", "gst_number": "", "address": "404, Ferry bell,Lodha medows", "city": "Pune", "state": "Maharashtra", "zipcode": "411016", "enable_online_settlement": "1", "commission_type": "Percentage", "commission": "50", "settlement_type":"Auto", "bank_holder_name": "Paresh", "account_number": "00111122236", "bank_name": "SBI", "account_type": "Saving", "ifsc": "HDFC0000001", "enable_franchise_login":"1", "login_email":"franchise@swipez.in", "password":"password1", "role_name":"Role 1" } ' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/franchise/save', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "franchise_code": "5", "franchise_name": "john Ppp", "contact_person_name":"Paresh", "email_id": "johndoe@swipez.in", "mobile": "9999999999", "pan_number": "", "aadhar_number": "", "gst_number": "", "address": "404, Ferry bell,Lodha medows", "city": "Pune", "state": "Maharashtra", "zipcode": "411016", "enable_online_settlement": "1", "commission_type": "Percentage", "commission": "50", "settlement_type":"Auto", "bank_holder_name": "Paresh", "account_number": "00111122236", "bank_name": "SBI", "account_type": "Saving", "ifsc": "HDFC0000001", "enable_franchise_login":"1", "login_email":"franchise@swipez.in", "password":"password1", "role_name":"Role 1" } ', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Update franchise `POST` `/api/v1/franchise/update` This endpoint allows you to update franchise. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | --------------------- | ------ | ----------------------------------- | | franchise\_id | string | Franchise id | | franchise\_name | string | Name of franchise. | | contact\_person\_name | string | Contact person name. | | email\_id | string | Email id of franchise. | | mobile | string | 10 digit mobile number of franchise | | pan\_number | string | 10 Char Pan number | | aadhar\_number | string | 12 digit Aadhar num | | gst\_number | string | 15 char GST number. | | address | string | Franchise address. | | city | string | Franchise city. | | state | string | Franchise state. | | zipcode | string | Franchise zipcode | | | string | | {% tabs %} {% tab title="200 " %} ``` { "success":"Franchise saved successfully", "status": "1", "franchise_id": "8545" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/franchise/update' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "franchise_id": "5", "franchise_name": "john Ppp", "contact_person_name":"Paresh", "email_id": "johndoe@swipez.in", "mobile": "9999999999", "pan_number": "", "aadhar_number": "", "gst_number": "", "address": "404, Ferry bell,Lodha medows", "city": "Pune", "state": "Maharashtra", "zipcode": "411016" } ' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/franchise/update', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "franchise_id": "5", "franchise_name": "john Ppp", "contact_person_name":"Paresh", "email_id": "johndoe@swipez.in", "mobile": "9999999999", "pan_number": "", "aadhar_number": "", "gst_number": "", "address": "404, Ferry bell,Lodha medows", "city": "Pune", "state": "Maharashtra", "zipcode": "411016" } ', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Delete franchise `POST` `/api/v1/franchise/delete` This endpoint allows you to delete franchise. #### Headers | Name | Type | Description | | ------------- | ------ | ----------------- | | Authorization | string | Bearer auth token | | Content-Type | string | application/json | #### Request Body | Name | Type | Description | | ------------- | ------- | ------------ | | franchise\_id | integer | Franchise id | {% tabs %} {% tab title="200 " %} ``` { "success":"Franchise saved successfully", "status": "1", "franchise_id": "8545" } ``` {% endtab %} {% endtabs %} #### Sample code {% tabs %} {% tab title="CURL" %} ```javascript curl --location --request POST '/api/v1/franchise/delete' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --form 'franchise_id="39"' ``` {% endtab %} {% tab title="PHP" %} ``` $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => '/api/v1/franchise/update', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array('franchise_id' => '1'), CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} # Webhooks Learn more about supported webhooks in invoicing and subscriptions Webhooks are events that notify you about the payment status. All Payment integrations should establish a webhook to listen to transaction events, like status changes on payments. Webhooks are HTTP callbacks that receive notification messages for events. Webhooks help you receive automatic updates and are significant for completing the integration with Swipez. Webhooks are triggered with a request from your side, for example, when a payment fails or success. Swipez notifies you once we get updates from the bank about the payment status. | Parameters | Description | | --------------------- | ---------------------------------------- | | transaction\_id | Swipez transaction id | | reference\_no | Reference number provided by Merchant | | status | Transaction status "success" or "failed" | | date | Transaction date time | | bank\_ref\_no | Bank reference number | | mode | Payment mode eg. Credit card, UPI | | amount | Transaction amount | | billing\_name | Payee name | | billing\_email | Payee email id | | billing\_mobile | Payee mobile number | | billing\_address | Payee address | | billing\_city | Payee city | | billing\_state | Payee state | | billing\_postal\_code | Payee pincode | | udf1 | Extra parameter provided by merchant | | udf2 | Extra parameter provided by merchant | | udf3 | Extra parameter provided by merchant | | udf4 | Extra parameter provided by merchant | | udf5 | Extra parameter provided by merchant |