{ "openapi": "3.0.0", "x-stoplight": { "id": "v3t7owhh461u5" }, "servers": [ { "url": "https://uat1.billdesk.com/u2", "description": "UAT server" }, { "url": "https://api.billdesk.com", "description": "PROD server" } ], "info": { "title": "Payments", "description": "This explorer allows merchants to evaluate APIs that are available in the BillDesk Payment Gateway API suite.\n - Only HMAC authentication is supported.\n - All APIs are RESTful and resource oriented.\n - Servers listed are applicable for the API explorer only.", "contact": { "name": "API Support", "url": "https://www.billdesk.com/helpcenter.htm", "email": "support@billdesk.com" }, "version": "2.5" }, "x-samples-languages": [ "shell", "json", "node", "java", "csharp" ], "paths": { "/payments/ve1_2/orders/create": { "post": { "summary": "Create Order", "operationId": "createOrder", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "order", "mercid": "BDMERCID", "amount": "300.00", "ru": "https://www.demourlmerchant.com/response", "orderid": "6yn4uhuz9e9bcw9qo6r6v4", "order_date": "2020-08-17T15:19:00+0530", "bdorderid": "OAFC19XTFD8TSP", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2" }, "next_step": "redirect", "itemcode": "DIRECT", "createdon": "2021-03-11T19:23:24+05:30", "currency": "356", "links": [ { "method": "GET", "rel": "self", "href": "https://www.sampleurl.com/request" }, { "headers": { "authorization": "OToken DEDC1071B77800A146B6E8D2530E0429E76520C151B40CC3325D8B6D9242CBA3A6BFA643E7E5596FBEBAE0F46A1FB1BCD099EBC1F59DCD82F390B6BC45FCE036F37F7F589BD687A691E1378F1FF432331C62E7E641E857C8F8A405A4BFE2F01B1EB8F3C69817D45F5DDE9DEE346ACABA1B7208DECA9E43CCE7AB3761553E23D9CB36A870C1819C15C7C4B1CFE2802DFD05F651AA537AB81787.4145535F55415431" }, "valid_date": "2020-08-17T15:49:00+05:30", "method": "POST", "rel": "redirect", "href": "https://www.billdesk.com/pgi/MerchantPayment/", "parameters": { "mercid": "BDMERCID", "bdorderid": "OAFC19XTFD8TSP" } } ], "status": "ACTIVE", "invoice": { "invoice_number": "MEINVU111111221133", "invoice_display_number": "11221133", "customer_name": "John Doe", "invoice_date": "2021-09-03T13:21:50+05:30", "gst_details": { "cgst": "8.00", "sgst": "8.00", "igst": "0.00", "gst": "16.00", "cess": "0.00", "gstincentive": "5.00", "gstpct": "16.00", "gstin": "12344567" } }, "device": { "accept_header": "text/html", "ip": "202.149.208.92", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "imei": "990000112233445", "init_channel": "internet", "mac": "11-AC-58-21-1B-AA", "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:51.0) Gecko/20100101 Firefox/51.0" } } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "order_date": { "type": "string", "description": "Merchant order generation date and time in YYYY-MM-DDThh:mm:ssTZD format", "example": "2023-03-14T15:14:39+05:30", "format": "date-time" }, "bdorderid": { "title": "bdorderid", "x-stoplight": { "id": "m13q2fo7bn801" }, "type": "string", "description": "Unique value generated by BillDesk for each order id generated using Create Order API" }, "next_step": { "title": "next_step", "x-stoplight": { "id": "ayox9qr52qx6o" }, "type": "string", "description": "Refers to the action to be taken by the merchant, for eg. redirect or capture_otp", "enum": [ "redirect", "capture_otp", "3ds2_challenge", "3ds2_frictionless" ] }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "createdon": { "title": "createdon", "x-stoplight": { "id": "k3ewegvbimz0g" }, "type": "string", "description": "object creation timestamp", "format": "date-time" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "links": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "rel": { "type": "string" }, "href": { "type": "string" }, "headers": { "type": "object", "properties": { "authorization": { "title": "authorization", "x-stoplight": { "id": "7j04iqr3yp3z3" }, "type": "string", "description": "Unique value generated by BillDesk for each request" } } }, "valid_date": { "type": "string" }, "parameters": { "type": "object", "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "bdorderid": { "title": "bdorderid", "x-stoplight": { "id": "m13q2fo7bn801" }, "type": "string", "description": "Unique value generated by BillDesk for each order id generated using Create Order API" }, "rdata": { "title": "rdata", "x-stoplight": { "id": "lftrd03d82vvp" }, "type": "string", "description": "Unique key generated by BillDesk for each request", "x-examples": {} } } } } } }, "status": { "type": "string", "enum": [ "ACTIVE" ], "description": "Represents the status of the order, with the following possible values:\n•\tACTIVE" }, "invoice": { "type": "object", "x-examples": { "Example 1": { "invoice_number": "MEINVU111111221133", "invoice_display_number": "11221133", "customer_name": "John Doe", "invoice_date": "2021-09-03T13:21:50+05:30", "gst_details": { "cgst": "8.00", "sgst": "8.00", "igst": "0.00", "gst": "16.00", "cess": "0.00", "gstincentive": "5.00", "gstpct": "16.00", "gstin": "12344567" } } }, "properties": { "invoice_number": { "type": "string", "description": "Unique number assigned by merchant for the invoice", "pattern": "^[A-Za-z0-9]{1,100}$", "example": "MEINVU111111221133" }, "invoice_display_number": { "type": "string", "description": "Invoice number to be displayed to the customer", "example": "11221133", "pattern": "^[A-Za-z0-9]{1,80}$" }, "customer_name": { "type": "string", "pattern": "^[A-Za-z0-9]{1,80}$", "example": "John Doe", "description": "Customer's name to be printed on invoice" }, "invoice_date": { "type": "string", "description": "Invoice generation date in the YYYYMMDD format", "format": "date", "example": "2021-09-03" }, "gst_details": { "type": "object", "properties": { "cgst": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "100.00" }, "sgst": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "100.00" }, "igst": { "type": "string", "example": "200.00", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gst": { "type": "string" }, "cess": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "50.00" }, "gstincentive": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gstpct": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gstin": { "type": "string", "pattern": "^[A-Za-z0-9]{1,80}$", "example": "29GGGGG1314R9Z6" } } } } }, "split_payment": { "type": "object", "x-examples": { "Example 1": { "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split payment amount will be settled.", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID" }, "amount": { "type": "string", "description": "Split Amount which is settled in the respective Split Merchant ID.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" } }, "description": "This object is applicable in case a merchant has opted to receive the settlement in multiple settlement accounts", "title": "split_payment_request" }, "mandate": { "type": "object", "properties": { "objectid": { "type": "string" }, "mercid": { "type": "string" }, "customer_refid": { "type": "string" }, "subscription_refid": { "type": "string" }, "subscription_desc": { "type": "string" }, "amount": { "type": "string" }, "amount_type": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "frequency": { "type": "string" }, "payment_method_type": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "mandateid": { "type": "string" }, "createdon": { "type": "string" }, "verification_error_code": { "type": "string" }, "verification_error_type": { "type": "string" }, "verification_error_desc": { "type": "string" } }, "x-examples": { "Example 1": { "objectid": "mandate", "mercid": "BDMERCID", "customer_refid": "CUSTREF00A00011", "subscription_refid": "SUBREF00A00011", "subscription_desc": "Family Plan", "amount": "1500.00", "amount_type": "maximum", "start_date": "2021-05-16", "end_date": "2029-10-22", "frequency": "adho", "payment_method_type": "card", "currency": "356", "status": "pending", "mandateid": "MA0DDD00050243", "createdon": "2021-05-16T18:23:11+05:30", "verification_error_code": "TRS0000", "verification_error_type": "success", "verification_error_desc": "Transaction Successful" } } }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } } }, "examples": { "Create order": { "value": { "mercid": "BDMERCID", "amount": "29999.28", "ru": "https://www.merchant.com", "orderid": "TEST00000090060", "createdon": "2023-11-22T15:43:54+05:30", "order_date": "2023-03-25T15:14:39+05:30", "bdorderid": "OAKU2U0V4C6B", "next_step": "redirect", "itemcode": "DIRECT", "currency": "356", "links": [ { "method": "GET", "rel": "self", "href": "https://www.some url.com/demo/TEST00000090060" }, { "headers": { "authorization": "OToken 47e627dddab9f33066a808b2e5d68c13d9a76b942bb36da8f2d823b9b1b7ed3ed5eb90bce16c75c15aa042ecd6b2adf33f9984b60183071133bad1702d7463b18fa46bed1346a1320675ea61f219d1725f5b6031b57bb860ea8f817cfc860faa91ad89041a66eb5b7776c94cf9f4309928a816a9bbbea5e6357d695aac1af458ceb21956323324a1b0a5eff043e6ef716a7c71c3444aab90a85154aadf6fde399db352a2ee6a.70675f706172616d5f656e6331" }, "valid_date": "2023-11-22T16:13:54+05:30", "method": "POST", "rel": "redirect", "href": "https://www.some url.com/demo", "parameters": { "mercid": "BDMERCID", "bdorderid": "OAKU2U0V4C6B", "rdata": "d7f81c024aef396a80f32c876a1f 60017f4ac50a75cf2a663cd6a81e8c8 37e9912cbf49aac6be28f98d19c1e16 0f7b88a6e730e736f0dc52c82689e70 b55.7561746b657931" } } ], "objectid": "order", "status": "ACTIVE" } }, "Create order with split payment": { "value": { "objectid": "order", "orderid": "UAT1002202300001", "bdorderid": "OAZG19XTTEVQSS", "mercid": "BDMERCID", "order_date": "2023-02- 09T10:00:45+05:30", "amount": "4000.00", "currency": "356", "ru": "https://www.merchanturl.com/", "additional_info": { "additional_info1": "NA", "additional_info2": "NA" }, "itemcode": "DIRECT", "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ], "createdon": "2023-02- 10T00:19:42+05:30", "next_step": "redirect", "links": [ { "href": "https://www.some url.com/demo", "rel": "self", "method": "GET" }, { "href": "https://www.redirecturl.io/form", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMERCID ", "bdorderid": "OAZG19XTTEVQSS", "rdata": "3e35f44cf9acd6a683d5c43b71b37f6ea6ae0fc7dbe227c1ea961e7011c6c4aebe5ceaa584c53ba8fc6bff05ec78ab552c58e1ef77ac20f719ac3c0c468df044.7561746b657931" }, "valid_date": "2023-02- 10T00:49:42+05:30", "headers": { "authorization": "O Token 8A20A6DF3BD7957AFC66FC562DED0D8B5966FB2C464E962E0BCADDB8B67F625169D9524423D9A36BC80282904EA6D49ACEECB2AA72B8C8CB4F187ECC9A35D39C3FE770A0B6EBC4EF38CC1F42CE4BCA744875E1152E0EFBDA01F02F3822DD8283E985105A146DD7D8C378106F08E628023ED459C579A10120182E3836ACF543A6922FC81C7682BB5E56B155FD47AC3F9FB18780EDFAFD1982F4.4145535F55415431" } } ], "status": "ACTIVE" } }, "Create order with Mandate": { "value": { "objectid": "order", "orderid": "order45608988", "bdorderid": "OAMA19XU6FRZTC", "mercid": "BDMERCID", "order_date": "2024-01-30T10: 59: 15+05: 30", "amount": "300.00", "currency": "356", "ru": "https://www.merchant.com/", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "NA", "additional_info4": "NA", "additional_info5": "NA", "additional_info6": "NA", "additional_info7": "NA" }, "itemcode": "DIRECT", "createdon": "2024-02-11T21: 54: 56+05: 30", "next_step": "redirect", "links": [ { "href": "https://www.billdesk.com/pgi/ve1_2/orders/order45608988", "rel": "self", "method": "GET" }, { "href": "https://uat1.billdesk.com/u2/web/v1_2/embeddedsdk ", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMERCID", "bdorderid": "OAMA19XU6FRZTC", "rdata": "8F143FB859C8F0C5CB14CA2718CA56BC9CB61766DC0B1CB2173305D94A9B664DEF08964B55A3D4CFA99D7D45B16F02EE8613C720626BD6A6E3F49377B6C49C5.4145535F55415431" }, "valid_date": "2024-02-12T02: 54: 56+05: 30", "headers": { "authorization": "OToken E88302C05CC3EF626619DC152DF3C6C305CE416F88B47E623763C2438E958150D0128314AE937C79A6C41F3F5513A0FB8F8C9358D970287D8CD6A0AED670BD833F94825D4FAA9BC6DE48EA16BABD2218F81481EA54688BEEC1AB35AC6C959CFC085D91B78C96582C2CFE001457E697344188B821C469B4ED0051AB334EB7395E6D07CFB235712C248C95CA082E7F89C8E28748BEF310612.4145535F55415431" } } ], "mandate": { "mercid": "BDMERCID", "customer_refid": "cust9199028201", "subscription_refid": "Sub92882992782701", "subscription_desc": "Term insurance", "amount": "200.00", "amount_type": "max", "start_date": "2024-02-11", "end_date": "2025-12-04", "frequency": "year", "currency": "356", "status": "initiated", "mandate_tokenid": "NA23DB00429155", "recurrence_rule": "after", "debit_day": "1", "createdon": "2024-02-11T21: 54: 56+05: 30" }, "status": "ACTIVE" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Invalid merchant config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "tags": [ "Order" ], "description": "This API can be used to initiate a payment or to set up a mandate along with a payment in the BillDesk Hosted Payment Page or BillDesk Web SDK workflow", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "order_date": { "type": "string", "description": "Merchant order generation date and time in YYYY-MM-DDThh:mm:ssTZD format", "example": "2023-03-14T15:14:39+05:30", "format": "date-time" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "settlement_lob": { "type": "string", "description": "Settlement line of business preconfigured by BillDesk for funds settlement to merchant account" }, "mandate_required": { "type": "string", "enum": [ "Y", "N" ], "description": "Value which represents if the customer is to be givrn the option to not set a mandate on the BillDesk Hosted Payment Page or Web SDK. Applicable for the One time payment & Mandate workflow \n\nY- Represents that setting the Mandate is mandatory and the customer does not have an option to turn off the mandate\n\nN- Represents that setting the Mandate is optional and the customer has an option to turn off the mandate. In this case, a one time payment will be made without the mandate" }, "customer": { "title": "customer", "x-examples": { "Example 1": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" } }, "type": "object", "properties": { "first_name": { "type": "string", "description": "Customer’s First Name", "example": "John" }, "last_name": { "type": "string", "description": "Customer’s Last Name", "example": "Doe" }, "mobile": { "type": "string", "description": "Customer’s Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979988" }, "mobile_alt": { "type": "string", "description": "Customer’s Alternate Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979982" }, "email": { "type": "string", "description": "Customer’s Email address", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$", "example": "abc@xyz.com" }, "email_alt": { "type": "string", "description": "Customer’s alternate Email Address", "example": "abc@xyz.com", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$" } }, "required": [ "first_name", "last_name" ] }, "avs": { "type": "object", "x-examples": { "Example 1": { "bankaccount": [ { "number": "12233445566", "ifsc": "IDBK10000002", "name": "John Doe" }, { "number": "12233445567", "ifsc": "IDBK10000002", "name": "John Doe" } ] } }, "description": "This API can be used to verify the bank account number by initiating a penny drop to the account. For upi, validation is done at acquiring bank end ", "title": "Account validation", "properties": { "bankaccounts": { "type": "array", "items": { "type": "object", "properties": { "number": { "description": "Customer's bank account number", "title": "bankacc_number", "x-stoplight": { "id": "9nwo0pwlz0qos" }, "type": "string", "pattern": "^\\\\d{9,18}$", "example": "12233445566" }, "ifsc": { "description": "IFSC of the bank account number", "title": "IFSC", "x-stoplight": { "id": "grn65kr3i0pk0" }, "type": "string", "pattern": "^[A-Za-z]{4}[a-zA-Z0-9]{7}$", "example": "IDBK10000002" }, "name": { "description": "Name of the bank account holder", "title": "bankaccount_holder_name", "x-stoplight": { "id": "jedjceugzit8g" }, "type": "string", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$" } }, "required": [ "number", "ifsc" ] } } } }, "device": { "type": "object", "x-stoplight": { "id": "bu2ij616i2uce" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "Device", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" } }, "required": [ "init_channel", "ip", "user_agent", "accept_header" ] }, "invoice": { "type": "object", "x-examples": { "Example 1": { "invoice_number": "MEINVU111111221133", "invoice_display_number": "11221133", "customer_name": "John Doe", "invoice_date": "2021-09-03T13:21:50+05:30", "gst_details": { "cgst": "8.00", "sgst": "8.00", "igst": "0.00", "gst": "16.00", "cess": "0.00", "gstincentive": "5.00", "gstpct": "16.00", "gstin": "12344567" } } }, "properties": { "invoice_number": { "type": "string", "description": "Unique number assigned by merchant for the invoice", "pattern": "^[A-Za-z0-9]{1,100}$", "example": "MEINVU111111221133" }, "invoice_display_number": { "type": "string", "description": "Invoice number to be displayed to the customer", "example": "11221133", "pattern": "^[A-Za-z0-9]{1,80}$" }, "customer_name": { "type": "string", "pattern": "^[A-Za-z0-9]{1,80}$", "example": "John Doe", "description": "Customer's name to be printed on invoice" }, "invoice_date": { "type": "string", "description": "Invoice generation date in the YYYYMMDD format", "format": "date", "example": "2021-09-03" }, "gst_details": { "type": "object", "properties": { "cgst": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "100.00" }, "sgst": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "100.00" }, "igst": { "type": "string", "example": "200.00", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gst": { "type": "string" }, "cess": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "50.00" }, "gstincentive": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gstpct": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gstin": { "type": "string", "pattern": "^[A-Za-z0-9]{1,80}$", "example": "29GGGGG1314R9Z6" } } } } }, "split_payment": { "type": "object", "x-examples": { "Example 1": { "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split payment amount will be settled.", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID" }, "amount": { "type": "string", "description": "Split Amount which is settled in the respective Split Merchant ID.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" } }, "description": "This object is applicable in case a merchant has opted to receive the settlement in multiple settlement accounts", "title": "split_payment_request" }, "mandate": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "customer_refid": "CUST614514520010012", "subscription_refid": "SUB614514510012", "subscription_desc": "Unlimited Plan", "start_date": "2023-02-08", "end_date": "2050-12-22", "amount": "774.00", "currency": "356", "frequency": "adho", "amount_type": "max" } }, "properties": { "mercid": { "type": "string", "description": "Unique identifier as defined by BillDesk for each merchant", "example": "BDMERCID", "pattern": "^[A-Za-z0-9]{1,10}$" }, "customer_refid": { "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CUSTREF00A00011" }, "subscription_refid": { "type": "string", "description": "Unique reference assigned by merchant for the subscription", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "SUBREF00A00011" }, "subscription_desc": { "type": "string", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "amount": { "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "200.28" }, "currency": { "type": "string", "description": "ISO currency code for the amount, with a value 356 for INR", "example": "356" }, "frequency": { "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n\n•\tweek - weekly\n•\tmnth - monthly\n•\tbimn – bi-monthly\n•\tqurt - quarterly\n•\tbian – bi-annually\n•\tyear - yearly\n•\tadho – adhoc\n\n", "enum": [ "mnth", "week", "bimn", "qurt", "bian", "year", "adho" ], "example": "adho" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] } }, "required": [ "mercid", "customer_refid", "subscription_refid", "subscription_desc", "start_date", "end_date", "amount", "currency", "frequency", "amount_type" ] }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } }, "required": [ "orderid", "mercid", "order_date", "amount", "currency", "ru", "itemcode" ] }, "examples": { "Create order": { "value": { "orderid": "TEST00000090061", "mercid": "BDMERCID", "order_date": "2023-03-25T15:14:39+05:30", "amount": "29999.28", "currency": "356", "ru": "https://www.merchant.com", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "123.0.0.1", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9" } } }, "Create order with split payment": { "value": { "device": { "init_channel": "internet", "ip": "136.232.199.34", "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:51.0) Gecko/20100101 Firefox/51.0" }, "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ], "mercid": "BDMERCID", "orderid": "UAT1002202300001", "amount": "4000.00", "order_date": "2023-02-09T10:00:45+05:30", "currency": "356", "ru": "https://www.merchanturl.com/", "itemcode": "DIRECT" } }, "Create order with Mandate ": { "value": { "mercid": "BDMERCID", "orderid": "order45608988", "amount": "300.00", "order_date": "2024-01-30T10: 59: 15+05: 30", "currency": "356", "ru": "https://www.merchant.com/", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2" }, "mandate": { "mercid": "BDMERCID", "currency": "356", "amount": "200.00", "customer_refid": "cust9199028201", "subscription_refid": "Sub92882992782701", "subscription_desc": "Term insurance", "start_date": "2024-02-11", "end_date": "2025-12-04", "frequency": "year", "amount_type": "max", "recurrence_rule": "after", "debit_day": "1" }, "mandate_required": "Y", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "123.0.0.1", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } } } } }, "description": "" } }, "parameters": [] }, "/payments/ve1_2/orders/get": { "post": { "summary": "Retrieve Order", "operationId": "retrieveOrder", "responses": { "200": { "description": "OK", "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } }, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "transaction", "transactionid": "X7890733918355", "orderid": "TST01092022004", "mercid": "BDMERCID", "transaction_date": "2022-09-01T00:38:25+05:30", "amount": "5.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "5.00", "currency": "356", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "txn_process_type": "collect", "bankid": "789", "itemcode": "DIRECT", "bank_ref_no": "224457208022", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "upi", "refundInfo": [ { "refundid": "X78907339183552", "refund_amount": "3.00", "currency": "356", "refund_date": "2022-09-01T00:40:06+05:30", "merc_refund_ref_no": "REFUNDREF0003", "refund_status": "0799" }, { "refundid": "X78907339183551", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-09-01T00:40:00+05:30", "merc_refund_ref_no": "REFUNDREF0002", "refund_status": "0799" } ] } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "surcharge": { "title": "surcharge", "x-stoplight": { "id": "u8bi4pr2xista" }, "type": "string", "description": "Customer surcharge in two decimals applied to the transaction amount, if any" }, "discount": { "title": "discount", "x-stoplight": { "id": "0dgp8etm5709j" }, "type": "string", "description": "Customer discount in two decimals applied to the transaction amount, if any" }, "charge_amount": { "title": "charge_amount", "x-stoplight": { "id": "m2z4sf48a8a5w" }, "type": "string", "description": "Total charge to the customer" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "bank_ref_no": { "title": "bank_ref_no", "x-stoplight": { "id": "tls0w5ung6eha" }, "type": "string", "description": "Transaction reference number generated by bank or acquirer " }, "auth_status": { "title": "auth_status", "x-stoplight": { "id": "35i21snltcrdq" }, "type": "string", "description": "Represents the authorization status of the transaction with the following possible values:\n•\t0300 - transaction is successful\n•\t0002 - transaction is pending for authorization\n•\t0399 - transaction failed", "enum": [ "0300", "0002", "0399" ] }, "transaction_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "transaction_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "transaction_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "refundInfo": { "type": "object", "x-stoplight": { "id": "0a9154jkzqr2x" }, "properties": { "refundInfo": { "type": "array", "items": { "type": "object", "properties": { "refundid": { "type": "string", "description": "Unique id generated by BillDesk for the refund" }, "refund_amount": { "type": "string", "description": "Refund amount in two decimals" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "refund_date": { "type": "string", "description": "BillDesk refund date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "merc_refund_ref_no": { "type": "string", "description": "Unique reference number generated by the merchant for the refund request" }, "refund_status": { "type": "string", "description": "Represents the refund status with the following values:\n•\t0799 – categorized as a refund, where the original transaction has been already settled \n•\t0699 – categorized as a cancellation, where the original transaction has not been settled\n" } } } } }, "description": "" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } } }, "examples": { "Response": { "value": { "objectid": "transaction", "transactionid": "U4560001099939", "orderid": "TEST0000009005", "mercid": "BDMERCID", "transaction_date": "2023-03-14T15:14:39+05:30", "amount": "299.28", "surcharge": "0.00", "discount": "0.00", "charge_amount": "299.28", "currency": "356", "txn_process_type": "y3ds", "bankid": "1HM", "itemcode": "DIRECT", "bank_ref_no": "string", "auth_status": "0300", "transaction_error_code": "TRP0000", "transaction_error_desc": "Transaction Pending", "transaction_error_type": "pending", "payment_method_type": "card" } } } } } } }, "description": "Merchant can retrieve the transaction either by using mercid and orderid or transactionid", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "orderid": "TST01092022004", "mercid": "BDMERCID", "refund_details": "true" } }, "properties": { "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "refund_details": { "type": "string", "description": "Refund information associated with the payment transaction. Merchants should pass this attribute in the request to ensure that the refund details [an array is returned if multiple partial refunds exist] are received in the response.\n\n⦁\ttrue for getting the refund details associated with the payment transaction.\n⦁\tfalse if refund details associated with the payment transaction is not required in the response.", "enum": [ "true", "false" ] } }, "required": [ "mercid" ] }, "examples": { "With refund details": { "value": { "orderid": "TEST0000009005", "mercid": "BDMERCID", "transactionid": "U4560001099939", "refund_details": "true" } }, "Without refund details": { "value": { "orderid": "TEST0000009005", "mercid": "BDMERCID", "transactionid": "U4560001099939" } } } } }, "description": "" }, "tags": [ "Order" ] } }, "/pgsi/ve1_2/mandatetokens/create": { "post": { "summary": "Create Mandate Token", "operationId": "createMandateToken", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "mandate_token", "mandate_tokenid": "NA12BF00383201", "mercid": "BDMONITOR", "customer_refid": "cust980823jkdyr9d912", "subscription_refid": "Sub98nmf0uh9f912", "subscription_desc": "9800000d1112", "start_date": "2023-12-29", "end_date": "2029-12-04", "amount": "2.00", "amount_type": "max", "currency": "356", "frequency": "year", "createdon": "2023-11-21T15:50:31+05:30", "ru": "https://www.billdesk.com/web/", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "123456789" }, "customer": { "first_name": "John", "last_name": "Doe", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com", "mobile": "9800000000", "mobile_alt": "9800000000" }, "device": { "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "init_channel": "internet", "ip": "192.168.1.1", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "browser_javascript_enabled": "true", "browser_java_enabled": "false", "browser_language": "en-US", "browser_color_depth": "32", "browser_screen_height": "601", "browser_screen_width": "657", "browser_tz": "-330" }, "status": "initiated", "recurrence_rule": "after", "debit_day": "6", "next_step": "redirect", "links": [ { "href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/initiate", "rel": "self", "method": "POST", "parameters": null, "valid_date": null, "headers": null }, { "href": "https://billdesk.techbulls.com/sdk/", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMONITOR", "mandate_tokenid": "NA12BF00383201" }, "valid_date": "2023-11-21T16:20:31+05:30", "headers": { "authorization": "OToken 6E8DAD70FD30FCC30377B6AEECE1FFCF25C939D0F60AAC55ED7B35B3995DCE2EE3A042486E1C1C729F501700D9504634075EA302E08304D8ADFED115BD91AF2E205AAFF9AC7EBB1722C91CF7C6AA671AE0E564B631B2770EFB7389089C7888722A19FD302B8D288BD3A8F6739DB0D77720CCB52E3867A1B455D26B94AA1E57AE07DCA932F0FA6F0772DB56016A5FDDE5CFBF3C8E4113B4AFFF.4145535F55415431" } } ] } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mandate_tokenid": { "title": "mandate_tokenid", "x-stoplight": { "id": "169b004872de3" }, "type": "string", "description": "Unique value generated by BillDesk for each mandate_token created by the merchant" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "subscription_refid": { "title": "subscription_refid", "x-stoplight": { "id": "0c9vc4zqx4a8c" }, "type": "string", "example": "SUBREF101", "description": "Unique reference assigned by merchant for a subscription" }, "subscription_desc": { "title": "subscription_desc", "x-stoplight": { "id": "lwkkeas7tgojy" }, "type": "string", "example": "Unlimited Plan", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "frequency": { "title": "frequency", "x-stoplight": { "id": "xrmygt1ddb1b6" }, "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n•week - weekly \n•mnth - monthly\n•bimn – bi-monthly\n•qurt - quarterly\n•bian – bi-annually\n•year - yearly\n•adho – adhoc\n", "enum": [ "week", "mnth", "bimn", "qurt", "bian", "year", "adho" ] }, "createdon": { "title": "createdon", "x-stoplight": { "id": "k3ewegvbimz0g" }, "type": "string", "description": "object creation timestamp", "format": "date-time" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "customer": { "title": "customer", "x-examples": { "Example 1": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" } }, "type": "object", "properties": { "first_name": { "type": "string", "description": "Customer’s First Name", "example": "John" }, "last_name": { "type": "string", "description": "Customer’s Last Name", "example": "Doe" }, "mobile": { "type": "string", "description": "Customer’s Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979988" }, "mobile_alt": { "type": "string", "description": "Customer’s Alternate Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979982" }, "email": { "type": "string", "description": "Customer’s Email address", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$", "example": "abc@xyz.com" }, "email_alt": { "type": "string", "description": "Customer’s alternate Email Address", "example": "abc@xyz.com", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$" } }, "required": [ "first_name", "last_name" ] }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "status": { "title": "auth_status", "x-stoplight": { "id": "35i21snltcrdq" }, "type": "string", "description": "Represents the authorization status of the transaction with the following possible values:\n•\t0300 - transaction is successful\n•\t0002 - transaction is pending for authorization\n•\t0399 - transaction failed", "enum": [ "0300", "0002", "0399" ] }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] }, "next_step": { "title": "next_step", "x-stoplight": { "id": "ayox9qr52qx6o" }, "type": "string", "description": "Refers to the action to be taken by the merchant, for eg. redirect or capture_otp", "enum": [ "redirect", "capture_otp", "3ds2_challenge", "3ds2_frictionless" ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "rel": { "type": "string" }, "href": { "type": "string" }, "headers": { "type": "object", "properties": { "authorization": { "title": "authorization", "x-stoplight": { "id": "7j04iqr3yp3z3" }, "type": "string", "description": "Unique value generated by BillDesk for each request" } } }, "valid_date": { "type": "string" }, "parameters": { "type": "object", "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "bdorderid": { "title": "bdorderid", "x-stoplight": { "id": "m13q2fo7bn801" }, "type": "string", "description": "Unique value generated by BillDesk for each order id generated using Create Order API" }, "rdata": { "title": "rdata", "x-stoplight": { "id": "lftrd03d82vvp" }, "type": "string", "description": "Unique key generated by BillDesk for each request", "x-examples": {} } } } } } } } }, "examples": { "Response": { "value": { "objectid": "mandate_token", "mandate_tokenid": "NA12BF00383201", "mercid": "BDMERCID", "customer_refid": "cust980823jkdyr9d912", "subscription_refid": "Sub98nmf0uh9f912", "subscription_desc": "9800000d1112", "start_date": "2023-12-29", "end_date": "2029-12-04", "amount": "2.00", "amount_type": "max", "currency": "356", "frequency": "year", "createdon": "2023-11-21T15:50:31+05:30", "ru": "https://www.merchant.com/ru/", "customer": { "first_name": "John", "last_name": "Doe", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com", "mobile": "9800000000", "mobile_alt": "9800000000" }, "device": { "init_channel": "internet", "ip": "192.168.1.1", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html" }, "status": "initiated", "recurrence_rule": "after", "debit_day": "6", "next_step": "redirect", "links": [ { "href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/initiate", "rel": "self", "method": "POST", "parameters": null, "valid_date": null, "headers": null }, { "href": "https://billdesk.techbulls.com/sdk/", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMERCID", "mandate_tokenid": "NA12BF00383201", "rdata": "9b035a3a8a8d0070dc6e93dbd0f09191b315cadc4c76706338aea0841c94310d0086a3b07797d549fee5ca28t51a8e435f149d9b34a138515dfb676b6cf80cd8.70675f706172616d5f656e6333" }, "valid_date": "2023-11-21T16:20:31+05:30", "headers": { "authorization": "OToken 6E8DAD70FD30FCC30377B6AEECE1FFCF25C939D0F60AAC55ED7B35B3995DCE2EE3A042486E1C1C729F501700D9504634075EA302E08304D8ADFED115BD91AF2E205AAFF9AC7EBB1722C91CF7C6AA671AE0E564B631B2770EFB7389089C7888722A19FD302B8D288BD3A8F6739DB0D77720CCB52E3867A1B455D26B94AA1E57AE07DCA932F0FA6F0772DB56016A5FDDE5CFBF3C8E4113B4AFFF.4145535F55415431" } } ] } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Invalid merchant config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "tags": [ "Order" ], "description": "This API is used to initate the process to Create a Mandate and is applicable for BillDesk Hosted Payments Page and BillDesk Web SDK workflows", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMONITOR", "customer_refid": "cust980823jkdyr9d912", "subscription_refid": "Sub98nmf0uh9f912", "subscription_desc": "9800000d1112", "currency": "356", "frequency": "year", "amount_type": "max", "amount": "2.00", "start_date": "2023-12-29", "end_date": "2029-12-04", "recurrence_rule": "after", "debit_day": "6", "customer": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" }, "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "123456789" }, "device": { "init_channel": "internet", "ip": "192.168.1.1", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "ru": "https://www.billdesk.com/web/" } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "subscription_refid": { "title": "subscription_refid", "x-stoplight": { "id": "0c9vc4zqx4a8c" }, "type": "string", "example": "SUBREF101", "description": "Unique reference assigned by merchant for a subscription" }, "subscription_desc": { "title": "subscription_desc", "x-stoplight": { "id": "lwkkeas7tgojy" }, "type": "string", "example": "Unlimited Plan", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "frequency": { "title": "frequency", "x-stoplight": { "id": "xrmygt1ddb1b6" }, "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n•week - weekly \n•mnth - monthly\n•bimn – bi-monthly\n•qurt - quarterly\n•bian – bi-annually\n•year - yearly\n•adho – adhoc\n", "enum": [ "week", "mnth", "bimn", "qurt", "bian", "year", "adho" ] }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] }, "customer": { "title": "customer", "x-examples": { "Example 1": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" } }, "type": "object", "properties": { "first_name": { "type": "string", "description": "Customer’s First Name", "example": "John" }, "last_name": { "type": "string", "description": "Customer’s Last Name", "example": "Doe" }, "mobile": { "type": "string", "description": "Customer’s Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979988" }, "mobile_alt": { "type": "string", "description": "Customer’s Alternate Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979982" }, "email": { "type": "string", "description": "Customer’s Email address", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$", "example": "abc@xyz.com" }, "email_alt": { "type": "string", "description": "Customer’s alternate Email Address", "example": "abc@xyz.com", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$" } }, "required": [ "first_name", "last_name" ] }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "device": { "type": "object", "x-stoplight": { "id": "bu2ij616i2uce" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "Device", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" } }, "required": [ "init_channel", "ip", "user_agent", "accept_header" ] }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } }, "required": [ "mercid", "customer_refid", "subscription_refid", "subscription_desc", "currency", "frequency", "amount_type", "amount", "start_date", "end_date", "customer", "ru", "device" ] }, "examples": { "Request": { "value": { "mercid": "BDMERCID", "customer_refid": "cust980823jkdyr9d912", "subscription_refid": "Sub98nmf0uh9f912", "subscription_desc": "9800000d1112", "currency": "356", "frequency": "year", "amount_type": "max", "amount": "2.00", "start_date": "2023-12-29", "end_date": "2029-12-04", "recurrence_rule": "after", "debit_day": "6", "customer": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" }, "device": { "init_channel": "internet", "ip": "192.168.1.1", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html" }, "ru": "https://merchant.com/ru" } } } } }, "description": "" } }, "parameters": [] }, "/pgsi/ve1_2/mandatetokens/update/create": { "post": { "summary": "Modify Mandate Token", "operationId": "modify-mandate-token", "responses": { "200": { "description": "OK", "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } }, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "mandate_token", "mandate_tokenid": "NA106900386835", "mandateid": "MA242A00269906", "mercid": "BDMONITOR", "customer_refid": "cusntrfdm", "subscription_refid": "Sub9rttfhj78t", "subscription_desc": "UAT Tefsting", "start_date": "2023-11-27", "end_date": "2026-12-04", "amount": "50.00", "amount_type": "maximum", "currency": "356", "frequency": "year", "createdon": "2023-11-28T11:33:08+05:30", "ru": "https://merchant.com/web", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "NA", "additional_info4": "NA", "additional_info5": "NA", "additional_info6": "NA", "additional_info7": "NA", "additional_info8": "NA", "additional_info9": "NA", "additional_info10": "NA" }, "customer": {}, "device": { "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "init_channel": "internet", "ip": "17.233.107.92", "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:51.0) Gecko/20100101Firefox/51.0", "accept_header": "text/html" }, "status": "initiated", "recurrence_rule": "on", "debit_day": "6", "action": "modify", "payment_method_type": "upi", "mandate_edit": { "end_date": "2023-12-28", "frequency": "mnth", "amount": "10.00", "amount_type": "fixed" }, "next_step": "redirect", "links": [ { "href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/initiate", "rel": "self", "method": "POST", "parameters": null, "valid_date": null, "headers": null }, { "href": "https://pguatweb.billdesk.io/pgtxnsimulator/v1_2/embeddedsdk", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMONITOR", "mandate_tokenid": "NA106900386835", "rdata": "{hsm:QUVTX1VBVDE=}1810E301DC2226B7F9BA7306DDBB836CEC6C7965AE7EB64FAE98BB73CAB238EB19FA6C6BB5705B059204E69994A60A2A699AF95" }, "valid_date": "2023-11-28T12:03:08+05:30", "headers": { "authorization": "OToken 3E6DCE2B15AC2ED1CFBFCAFA43600A084678AB3593E267E6831EF77D9E595377E8AF9E48BCD36AD32DEF7D44DA16085CB98E2C9CD797C8F00C496077F159E3457F8AC2AFEBA53D9AAE0DD1E04A9EA21F26325DC17384086F7AA79F17EFE7DFC4A4EECD9CAA44345F791D6BBC58BF03B5B8A7F9E806392AD02BC38C06BA4CFC479A6FD9E83918F71162FD8D7A06A317B3419B6EEC8253D4064.4145535F55415431" } } ] } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mandate_tokenid": { "title": "mandate_tokenid", "x-stoplight": { "id": "169b004872de3" }, "type": "string", "description": "Unique value generated by BillDesk for each mandate_token created by the merchant" }, "mandateid": { "title": "mandateid", "x-stoplight": { "id": "joq1b0hwy6hce" }, "type": "string", "description": "Unique mandateid created by BillDesk", "pattern": "^[A-Za-z0-9]{1,20}$", "example": "MA19E400049927" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "subscription_refid": { "title": "subscription_refid", "x-stoplight": { "id": "0c9vc4zqx4a8c" }, "type": "string", "example": "SUBREF101", "description": "Unique reference assigned by merchant for a subscription" }, "subscription_desc": { "title": "subscription_desc", "x-stoplight": { "id": "lwkkeas7tgojy" }, "type": "string", "example": "Unlimited Plan", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "amount": { "title": "subscription_amount", "x-stoplight": { "id": "7j61bmv2v1u41" }, "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "example": "2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "frequency": { "title": "frequency", "x-stoplight": { "id": "xrmygt1ddb1b6" }, "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n•week - weekly \n•mnth - monthly\n•bimn – bi-monthly\n•qurt - quarterly\n•bian – bi-annually\n•year - yearly\n•adho – adhoc\n", "enum": [ "week", "mnth", "bimn", "qurt", "bian", "year", "adho" ] }, "createdon": { "title": "createdon", "x-stoplight": { "id": "k3ewegvbimz0g" }, "type": "string", "description": "object creation timestamp", "format": "date-time" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "customer": { "title": "customer", "x-examples": { "Example 1": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" } }, "type": "object", "properties": { "first_name": { "type": "string", "description": "Customer’s First Name", "example": "John" }, "last_name": { "type": "string", "description": "Customer’s Last Name", "example": "Doe" }, "mobile": { "type": "string", "description": "Customer’s Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979988" }, "mobile_alt": { "type": "string", "description": "Customer’s Alternate Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979982" }, "email": { "type": "string", "description": "Customer’s Email address", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$", "example": "abc@xyz.com" }, "email_alt": { "type": "string", "description": "Customer’s alternate Email Address", "example": "abc@xyz.com", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$" } }, "required": [ "first_name", "last_name" ] }, "device": { "type": "object", "x-stoplight": { "id": "bu2ij616i2uce" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "Device", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" } }, "required": [ "init_channel", "ip", "user_agent", "accept_header" ] }, "status": { "title": "subscription_status", "x-stoplight": { "id": "y0fyz4zqhcknd" }, "type": "string", "description": "Represents the status of the mandate and depends upon the linked payment method. \n\nThe following values are possible:\ncard, upi\n•\tinitiated - mandate request has been initiated, and this status is applicable for the SDK based workflow\n•\tpending - mandate request has been initiated and the linked payment method is not yet validated\n•\tactive – linked payment method has been validated and recurring charges can be processed\n•\trejected - mandate has been rejected by the issuer or payment provider\n•\tdeleted - mandate has been deleted by the customer from the merchant channel\n•\tcancelled – mandate has been stopped by customer from the issuer channel\n•\tsuspended – mandate has been temporarily suspended by the issuer or payment provider\nbankaccount\n•\tpending – mandate request has been sent for account verification to NPCI\n•\tactive – mandate is active and recurring charges can be processed\n•\tdelete_initiated – mandate delete request is initiated by the customer or the merchant\n•\tdeleted – mandate is deleted after confirmation from NPCI\n•\trejected – mandate is rejected by NPCI\n" }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] }, "action": { "type": "string", "enum": [ "modify", "delete" ] }, "payment_method_type": { "type": "string" }, "mandate_edit": { "type": "object", "properties": { "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "frequency": { "title": "frequency", "x-stoplight": { "id": "xrmygt1ddb1b6" }, "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n•week - weekly \n•mnth - monthly\n•bimn – bi-monthly\n•qurt - quarterly\n•bian – bi-annually\n•year - yearly\n•adho – adhoc\n", "enum": [ "week", "mnth", "bimn", "qurt", "bian", "year", "adho" ] }, "amount": { "title": "subscription_amount", "x-stoplight": { "id": "7j61bmv2v1u41" }, "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "example": "2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] } } }, "next_step": { "title": "next_step", "x-stoplight": { "id": "ayox9qr52qx6o" }, "type": "string", "description": "Refers to the action to be taken by the merchant, for eg. redirect or capture_otp", "enum": [ "redirect", "capture_otp", "3ds2_challenge", "3ds2_frictionless" ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "rel": { "type": "string" }, "method": { "type": "string" }, "parameters": { "type": "object", "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "mandate_token_id": { "title": "mandate_tokenid", "x-stoplight": { "id": "169b004872de3" }, "type": "string", "description": "Unique value generated by BillDesk for each mandate_token created by the merchant" }, "rdata": { "title": "rdata", "x-stoplight": { "id": "lftrd03d82vvp" }, "type": "string", "description": "Unique key generated by BillDesk for each request", "x-examples": {} } } }, "valid_date": { "type": "string" }, "headers": { "type": "object", "properties": { "authorization": { "title": "authorization", "x-stoplight": { "id": "7j04iqr3yp3z3" }, "type": "string", "description": "Unique value generated by BillDesk for each request" } } } } } } } }, "examples": { "Modify response": { "value": { "objectid": "mandate_token", "mandate_tokenid": "NA106900386835", "mandateid": "MA242A00269906", "mercid": "BDMERCID", "customer_refid": "cusntrfdm", "subscription_refid": "Sub9rttfhj78t", "subscription_desc": "UAT Tefsting", "start_date": "2023-11-27", "end_date": "2026-12-04", "amount": "50.00", "amount_type": "maximum", "currency": "356", "frequency": "year", "createdon": "2023-11-28T11:33:08+05:30", "ru": "https://merchant.com/web", "customer": {}, "device": { "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "init_channel": "internet", "ip": "17.233.107.92", "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:51.0) Gecko/20100101Firefox/51.0", "accept_header": "text/html" }, "status": "initiated", "recurrence_rule": "on", "debit_day": "6", "action": "modify", "payment_method_type": "upi", "mandate_edit": { "end_date": "2023-12-28", "frequency": "mnth", "amount": "10.00", "amount_type": "fixed" }, "next_step": "redirect", "links": [ { "href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/initiate", "rel": "self", "method": "POST", "parameters": null, "valid_date": null, "headers": null }, { "href": "https://pguatweb.billdesk.io/pgtxnsimulator/v1_2/embeddedsdk", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMONITOR", "mandate_tokenid": "NA106900386835", "rdata": "9dc6a485c0896aa0a85c83a3ad295e9dea6ef0b12ac3aa3a05911bccf33cd45edfc1fb18df7b84017b74d3daaf9def5950206c17672e80583d79904d076bb9.70675f706172616d5f656e6333" }, "valid_date": "2023-11-28T12:03:08+05:30", "headers": { "authorization": "OToken 3E6DCE2B15AC2ED1CFBFCAFA43600A084678AB3593E267E6831EF77D9E595377E8AF9E48BCD36AD32DEF7D44DA16085CB98E2C9CD797C8F00C496077F159E3457F8AC2AFEBA53D9AAE0DD1E04A9EA21F26325DC17384086F7AA79F17EFE7DFC4A4EECD9CAA44345F791D6BBC58BF03B5B8A7F9E806392AD02BC438C06BA4CFC479A6FD9E83918F71162FD8D7A06A317B3419B6EEC8253D4064.4145535F55415431" } } ] } }, "Delete Response": { "value": { "objectid": "mandate_token", "mandate_tokenid": "NA180F00386854", "mandateid": "MA242A00269906", "mercid": "BDMERCID", "customer_refid": "cusntrfdm", "subscription_refid": "Sub9rttfhj78t", "subscription_desc": "UAT Tefsting", "start_date": "2023-11-27", "end_date": "2026-12-04", "amount": "50.00", "amount_type": "maximum", "currency": "356", "frequency": "year", "createdon": "2023-11-28T11:51:46+05:30", "ru": "https://merchant.com/web", "customer": {}, "device": { "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "init_channel": "internet", "ip": "17.233.107.92", "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:51.0) Gecko/20100101Firefox/51.0", "accept_header": "text/html" }, "status": "initiated", "recurrence_rule": "on", "debit_day": "6", "action": "delete", "payment_method_type": "upi", "next_step": "redirect", "links": [ { "href": "https://pguat.billdesk.io/pgsi/v1_2/mandates/token/initiate", "rel": "self", "method": "POST", "parameters": null, "valid_date": null, "headers": null }, { "href": "https://pguatweb.billdesk.io/pgtxnsimulator/v1_2/embeddedsdk", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMONITOR", "mandate_tokenid": "NA180F00386854" }, "valid_date": "2023-11-28T12:21:46+05:30", "headers": { "authorization": "OToken 7B1731C70832A8AA461FEBC73010B510BBA96F3772393F49A9BA22D1C5050B5A232659EBCA96FC3DFDB56E74CF5CB5F0F65003BB2A702B52A42FDEC446CD193D0CEAFAE70FD0CC8B6B012E9326BFD52D64AD69CD2252459A9E2DF3B07F914A5A3CE648628C2CA90683BD9CD0E639CBA93ACFA3C5F84D3DFD0A6BC52E529558259356436D9740F3121E35C26530EE73C5460DB2C884556C7448.4145535F55415431" } } ] } } } } } } }, "description": "This API is used to either modify certain attributes of an existing mandate or delete a mandate", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMONITOR", "mandateid": "MA242A00269906", "action": "modify", "mandate_edit": { "amount": "10.00", "frequency": "mnth", "amount_type": "fixed", "end_date": "2023-12-28" }, "ru": "https://merchant.com/web" } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "mandateid": { "title": "mandateid", "x-stoplight": { "id": "joq1b0hwy6hce" }, "type": "string", "description": "Unique mandateid created by BillDesk", "pattern": "^[A-Za-z0-9]{1,20}$", "example": "MA19E400049927" }, "action": { "type": "string", "description": "Attribute to specify if the mandate has to be edited or deleted", "enum": [ "modify", "delete" ] }, "mandate_edit": { "type": "object", "description": "Required if action= modify", "properties": { "amount": { "title": "subscription_amount", "x-stoplight": { "id": "7j61bmv2v1u41" }, "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "example": "2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$" }, "frequency": { "title": "frequency", "x-stoplight": { "id": "xrmygt1ddb1b6" }, "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n•week - weekly \n•mnth - monthly\n•bimn – bi-monthly\n•qurt - quarterly\n•bian – bi-annually\n•year - yearly\n•adho – adhoc\n", "enum": [ "week", "mnth", "bimn", "qurt", "bian", "year", "adho" ] }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" } } }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" } }, "required": [ "mercid", "mandateid", "action", "ru" ] }, "examples": { "Modify Request": { "value": { "mercid": "BDMERCID", "mandateid": "MA242A00269906", "action": "modify", "mandate_edit": { "amount": "10.00", "frequency": "mnth", "amount_type": "fixed", "end_date": "2023-12-28" }, "ru": "https://merchant.com/web" } }, "Delete Request": { "value": { "mercid": "BDMERCID", "mandateid": "MA242A00269906", "action": "delete", "ru": "https://merchant.com/web" } } } } } }, "tags": [ "Order" ] } }, "/payments/ve1_2/transactions/create": { "post": { "summary": "Create Transaction", "description": "This endpoint creates a new transaction to initiate a charge using a payment method.", "operationId": "createTransaction", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "transaction", "transactionid": "U4560001099951", "orderid": "ORDERID14032023003", "mercid": "BDMERCID", "transaction_date": "2023-03-14T15:17:30+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "VDDIRECT", "auth_status": "0002", "transaction_error_code": "TRP0000", "transaction_error_desc": "Transaction Pending", "transaction_error_type": "pending", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxx0000", "type": "DEBIT", "card_end": "0000", "network": "VISA", "issuer": "SBI" }, "next_step": "3ds2_challenge", "links": [ { "href": "https://www.issueurl.com/page.jsp", "rel": "redirect", "method": "post", "parameters": { "creq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJlZjU3OTMzYy04YmM4LTQ3YTEtYjFlNC04ZDE4NjM3ZTM2YzYiLCJhY3NUcmFuc0lEIjoiMDViYjAwZGItY2U0Ni00ODBiLWEyNWItZjJhNWU5YmMxOGJlIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0=" } } ] } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "surcharge": { "title": "surcharge", "x-stoplight": { "id": "u8bi4pr2xista" }, "type": "string", "description": "Customer surcharge in two decimals applied to the transaction amount, if any" }, "discount": { "title": "discount", "x-stoplight": { "id": "0dgp8etm5709j" }, "type": "string", "description": "Customer discount in two decimals applied to the transaction amount, if any" }, "charge_amount": { "title": "charge_amount", "x-stoplight": { "id": "m2z4sf48a8a5w" }, "type": "string", "description": "Total charge to the customer" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "auth_status": { "title": "auth_status", "x-stoplight": { "id": "35i21snltcrdq" }, "type": "string", "description": "Represents the authorization status of the transaction with the following possible values:\n•\t0300 - transaction is successful\n•\t0002 - transaction is pending for authorization\n•\t0399 - transaction failed", "enum": [ "0300", "0002", "0399" ] }, "transaction_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "transaction_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "transaction_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "next_step": { "title": "next_step", "x-stoplight": { "id": "ayox9qr52qx6o" }, "type": "string", "description": "Refers to the action to be taken by the merchant, for eg. redirect or capture_otp", "enum": [ "redirect", "capture_otp", "3ds2_challenge", "3ds2_frictionless" ] }, "card": { "type": "object", "x-examples": { "Example 1": { "masked_value": "xxxxxxxxxxxx8556", "type": "CREDIT", "card_end": "8556", "network": "VISA", "issuer": "HDFC Bank", "cardaccountid": "CA03E63F000027391234", "coft_consent": "true", "cardaccount": { "objectid": "cardaccount", "mercid": "BDMERCID", "customer_refid": "TST1305202312260002", "cardaccountid": "CA026D01000027391234", "orderid": "TXN1305202312260002", "masked_value": "xxxxxxxxxxxx8556", "holder_name": "NA", "issuer": "HDFC BANK", "network": "VISA", "status": "ACTIVE", "coft_consent": "true", "createdon": "2023-05-13T12:28:41+05:30", "network_token": { "token_ref_no": "55933247caa42c4842c012bb81641234", "token_expiry_month": "12", "token_expiry_year": "2025", "status": "ACTIVE", "createdon": "2023-05-13T12:28:41+05:30" } } } }, "properties": { "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Masked card number, with the last four digits", "example": "xxxxxxxxxxxx1001" }, "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "card_end": { "type": "string" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card Network", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" }, "cardaccountid": { "title": "cardaccountid", "x-stoplight": { "id": "12f6yszzh3x5y" }, "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "CA0AAEF9000000000123" }, "coft_consent": { "type": "string" }, "cardaccount": { "type": "object", "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "cardaccountid": { "type": "string" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "masked_value": { "type": "string" }, "holder_name": { "title": "holder_name", "x-stoplight": { "id": "azsrpizyvmymk" }, "type": "string", "description": "Cardholder name" }, "cardaccount_status": { "type": "string" }, "createdon": { "type": "string" }, "network_token": { "type": "object", "properties": { "token_ref_no": { "type": "string" }, "token_expiry_month": { "type": "string" }, "token_expiry_year": { "type": "string" }, "status": { "type": "string" }, "createdon": { "type": "string" } } }, "cardaccount_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "cardaccount_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "cardaccount_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" } } } }, "title": "" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "links": { "type": "object", "x-stoplight": { "id": "7t5udyb6ilh37" }, "x-examples": { "Example 1": { "links": [ { "href": "https://wwww.issuerurl.com/somepage", "rel": "redirect", "method": "post", "parameters": { "creq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIzYjFlYmQ5NC04NTZhLTRlYjEtYTJlMS00MWZkNTdjZGFkZjAiLCJhY3NUcmFuc0lEIjoiOGMzMzk3NTItMjNmMS00NmZlLThmNzEtMzAwZjAyMzY0NjcxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0=" } } ] } }, "description": "Associated links with the object, and contains the issuer URL that will be provided in the redirect authentication workflow", "title": "links", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string", "description": "Issuer response URL" }, "rel": { "type": "string", "description": "Fixed value as redirect" }, "method": { "type": "string", "enum": [ "POST" ] }, "parameters": { "description": "Parameters that are used to redirect the customer to the issuer URL", "type": "object", "x-examples": { "Example 1": { "tranid": "973712065583009734440001099962", "AccuCardholderId": "90926094409", "AccuReturnURL": "https://www.merchanturl.com/response.jsp", "session": "U4440001099962", "AccuGuid": "15e66a3b-956e-42f8-84d4-859e3e8c9fed", "TermUrl": "https://www.merchanturl.com/response.jsp", "AccuRequestId": "YjIxM2ZiZGUyMGY2MmNjZWE5YWQ1NGE5OGNiZDUyZjkyYThlMDFiYjFkMTY1Yjc0ZTI4NTgxNDA1MGRiNzE0Ng==", "cardend": "4938" } }, "title": "parameters", "properties": { "creq": { "type": "string", "description": "Challenge request message or payment message for 3ds2.0 protocol authentication" }, "bdcreq": { "type": "string", "description": "Challenge request message or payment message for \n3ds2.0 protocol authentication (Threeds method url flow)" }, "tranid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuCardholderId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuReturnURL": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "session": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuGuid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuRequestId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } } } } } } }, "avs": { "type": "object", "x-examples": { "Example 1": { "bankaccount": [ { "number": "xxxxxxxxx5566", "ifsc": "IDBK10000002", "name": "John Doe" }, { "number": "xxxxxxxxx5567", "ifsc": "IDBK10000002", "name": "John Doe" } ], "account_matched": "true", "name_matched": "true" } }, "properties": { "bankaccount": { "type": "array", "description": "Details of the bank account", "items": { "type": "object", "properties": { "number": { "title": "bankacc_number", "x-stoplight": { "id": "9nwo0pwlz0qos" }, "type": "string", "description": "Bank account number", "pattern": "^\\\\d{9,18}$", "example": "12233445566" }, "ifsc": { "title": "IFSC", "x-stoplight": { "id": "grn65kr3i0pk0" }, "type": "string", "description": "IFSC of the bank account number", "pattern": "^[A-Za-z]{4}[a-zA-Z0-9]{7}$", "example": "IDBK10000002" }, "name": { "title": "bankaccount_holder_name", "x-stoplight": { "id": "jedjceugzit8g" }, "type": "string", "description": "Name of the bank account holder", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$" } } } }, "account_matched": { "type": "string", "description": "Boolean value (true or false) that indicates the status of account matching", "enum": [ "true", "false" ] }, "name_matched": { "type": "string", "description": "Boolean value (true or false) that indicates the status of name matching", "enum": [ "true", "false" ] } }, "description": "" }, "mandate": { "type": "object", "properties": { "objectid": { "type": "string" }, "mercid": { "type": "string" }, "customer_refid": { "type": "string" }, "subscription_refid": { "type": "string" }, "subscription_desc": { "type": "string" }, "amount": { "type": "string" }, "amount_type": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "frequency": { "type": "string" }, "payment_method_type": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "mandateid": { "type": "string" }, "createdon": { "type": "string" }, "verification_error_code": { "type": "string" }, "verification_error_type": { "type": "string" }, "verification_error_desc": { "type": "string" } }, "x-examples": { "Example 1": { "objectid": "mandate", "mercid": "BDMERCID", "customer_refid": "CUSTREF00A00011", "subscription_refid": "SUBREF00A00011", "subscription_desc": "Family Plan", "amount": "1500.00", "amount_type": "maximum", "start_date": "2021-05-16", "end_date": "2029-10-22", "frequency": "adho", "payment_method_type": "card", "currency": "356", "status": "pending", "mandateid": "MA0DDD00050243", "createdon": "2021-05-16T18:23:11+05:30", "verification_error_code": "TRS0000", "verification_error_type": "success", "verification_error_desc": "Transaction Successful" } } }, "upi": { "type": "object", "x-examples": { "Example 1": { "upi": { "vpa": "billdesk@upi", "masked_vpa": "xxxxxx@upi" } } }, "title": "upi-response", "description": "Response of upi object in case of upi collect flow", "properties": { "upi": { "type": "object", "properties": { "vpa": { "type": "string", "description": "unmasked value of vpa" }, "masked_vpa": { "type": "string", "description": "masked value of vpa" } } } } }, "payment_category": { "title": "payment_category", "x-stoplight": { "id": "epd66eokga23s" }, "type": "string", "description": "Payment Category Code, defines the transaction belonging to the payment mode.\n• 00 - Card Gateway\n• 01 - Netbanking\n• 02 - Credit card\n• 03 - Debit card\n• 04 - Cash card\n• 05 - Mobile wallet\n• 10 - UPI\n• 11 - Bharat QR\n• 12 - Loan EMI\n• 13 - NEFT\n• 18 - UPI Credit\n• 19 - ENACH\n• 20 - CBDC\n• 21 - UPI Prepaid Wallet\n• 22 - UPI Credit Line", "example": "18" }, "me_ref_id": { "title": "me_ref_id", "x-stoplight": { "id": "5gfw31bjgpf6x" }, "type": "string", "description": "Unique identifier for a merchant, defined by the acquiring bank as a 6 digit code", "example": "545963" } } }, "examples": { "Frictionless flow": { "value": { "objectid": "transaction", "transactionid": "U4560001099939", "orderid": "ORDERID14032023002", "mercid": "BDMERCID", "transaction_date": "2023-03-14T15:14:39+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "VDDIRECT", "bank_ref_no": "123456", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxx1008", "type": "DEBIT", "card_end": "1008", "network": "VISA", "issuer": "SBI" }, "payment_category": "02", "me_ref_id": "545963" } }, "Challenge flow": { "value": { "objectid": "transaction", "transactionid": "U4560001099939", "orderid": "ORDERID14032023002", "mercid": "BDMERCID", "transaction_date": "2023-03-14T15:14:39+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "VDDIRECT", "bank_ref_no": "123456", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxx1008", "type": "DEBIT", "card_end": "1008", "network": "VISA", "issuer": "SBI" }, "payment_category": "02", "me_ref_id": "545963" } }, "Rupay Redirect flow": { "value": { "objectid": "transaction", "transactionid": "Z4561585963448", "orderid": "ORDER453673", "mercid": "BDMERCID", "transaction_date": "2023-12-06T13:58:01+05:30", "amount": "1.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "1.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "RDDIRECT", "bank_ref_no": "334013490494", "auth_status": "0002", "transaction_error_code": "TRP0000", "transaction_error_desc": "Transaction Pending", "transaction_error_type": "pending", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxx5844", "type": "DEBIT", "card_end": "5844", "network": "RUPAY", "issuer": "Bank of Baroda" }, "next_step": "redirect", "links": [ { "href": "https://www.issueurl.com/page.jsp", "rel": "redirect", "method": "POST", "parameters": { "tranid": "100312023120600000000961849608", "AccuCardholderId": "2023120608280214341293aY3xQ1cD", "AccuReturnURL": "https://www.merchanturl.com/response.jsp", "session": "ZUR31585963448", "AccuGuid": "8a2c4427-8b2d-4885-a183-c0fec906be9d", "TermUrl": "https://www.billdesk.com/pgidsk/PGIGatewayResponse/UR3", "AccuRequestId": "MzUzYjY0ZjhlOGJjZTZmMzcwMGZiYmY0MjdhYjFhOTQyMjZkZWE5MTk5MmE2Zjk2M2M4ZjM0ZTBjOWVmNGQ2MA==", "cardend": "5844" } } ], "payment_category": "03", "me_ref_id": "545963" } }, "Rupay OTP flow": { "value": { "objectid": "transaction", "transactionid": "ZUR31583340458", "orderid": "ORDERID1430632023005", "mercid": "BDMERCID", "transaction_date": "2023-12-05T12:34:54+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "444", "itemcode": "RDDIRECT", "bank_ref_no": "333912357007", "auth_status": "0002", "transaction_error_code": "TRP0000", "transaction_error_desc": "Transaction Pending", "transaction_error_type": "pending", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxx5844", "type": "DEBIT", "card_end": "5844", "network": "RUPAY", "issuer": "Bank of Baroda" }, "next_step": "capture_otp", "customer_message": "Please enter OTP sent to your mobile", "payment_category": "03", "me_ref_id": "545963" } }, "Recurring payment or subsequent charge for a mandate response (eNach)": { "value": { "objectid": "transaction", "transactionid": "UENY0000933887", "orderid": "ENYTEST0112", "mercid": "BDMERCID", "transaction_date": "2020-11-04T01:23:04+05:30", "amount": "200.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "200.00", "currency": "356", "txn_process_type": "si", "bankid": "ENY", "itemcode": "DIRECT", "bank_ref_no": "NA", "auth_status": "0002", "transaction_error_code": "TRP0000", "transaction_error_desc": "Transaction Pending", "transaction_error_type": "pending", "payment_method_type": "bankaccount", "mandateid": "MA1F6200153273", "subscription_refid": "Sub9171999111", "payment_category": "01", "me_ref_id": "545963" } }, "Decoupled flow": { "value": { "objectid": "transaction", "transactionid": "ZCY61818581307", "orderid": "UAT1541151862", "mercid": "BDMERCID", "transaction_date": "2024-03-12T14:40:51+05:30", "amount": "1.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "1.00", "currency": "356", "ru": "https://www.someurl.com/", "txn_process_type": "y3ds", "bankid": "CY6", "itemcode": "DIRECT", "bank_ref_no": "T84759", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "T84759", "eci": "02", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxx4183", "type": "CREDIT", "card_end": "4183", "network": "MASTER", "issuer": "Standard Chartered Bank" }, "payment_category": "02", "me_ref_id": "545963" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Invalid merchant config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "orderid": "ORDERID14032023003", "amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "authentication_type": "3ds2", "3ds_parameter": "merchant", "txn_process_type": "3ds", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.2", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "card": { "number": "4000020000000000", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123" } } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "authentication_type": { "title": "authentication_type", "x-stoplight": { "id": "c33ke2q5rl7ql" }, "type": "string", "description": "Represents the type of authentication initiated in the request, will be fixed value - 3ds2", "enum": [ "3ds2" ], "example": "3ds2" }, "3ds_parameter": { "title": "3ds_parameter", "x-stoplight": { "id": "9cf00xo1tntr9" }, "type": "string", "enum": [ "merchant" ], "description": "Value that determines which entity will capture the device attributes, possible values are merchant" }, "txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "device": { "type": "object", "x-stoplight": { "id": "1dup8vlut7f5l" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" }, "browser_language": { "type": "string", "description": "Value representing the browser language, returned from navigator.language property, for eg. en-US", "maxLength": 5, "example": "en-US", "pattern": "^[A-Za-z\\\\-]{2,5}$" }, "browser_javascript_enabled": { "type": "string", "enum": [ "true", "false" ], "description": "Boolean (true or false) that represents the ability of the cardholder browser to execute JavaScript.\nNote – if true, additional attributes of browser_tz, browser_color_depth, browser_java_enabled, browser_screen_height, browser_screen_width are mandatory" }, "browser_tz": { "type": "string", "description": "Time-zone offset in minutes between UTC and the Cardholder browser local time.\n\nNote that the offset is positive if the local time zone is behind UTC and negative if it is ahead. For eg. if UTC -5 hours then browser_tz = 300 and if UTC +5 hours then browser_tz = -300’", "pattern": "^[0-9\\\\+\\\\-]{2,6}$", "maxLength": 6, "example": "-330" }, "browser_color_depth": { "type": "string", "description": "Value representing the bit depth of the colour palette for displaying images, in bits per pixel.\n\nObtained from Cardholder browser using the screen.Color.Depth property. In case the actual vaue does not exist in the allowed values, use the closest lower value,for eg. 32", "maxLength": 5, "pattern": "^[0-9]{2,5}$", "example": "652" }, "browser_java_enabled": { "type": "string", "description": "Boolean (true or false) that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property", "enum": [ "true", "false" ] }, "browser_screen_height": { "type": "string", "description": "Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property for eg. 601", "pattern": "^[0-9]{2,5}$", "example": "452", "maxLength": 5 }, "browser_screen_width": { "type": "string", "description": "Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property, for eg. 657", "pattern": "^[0-9]{2,5}$", "example": "702", "maxLength": 5 } }, "required": [ "init_channel", "ip", "user_agent", "accept_header", "browser_language", "browser_javascript_enabled" ] }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "card": { "oneOf": [ { "type": "object", "x-stoplight": { "id": "1xxgnveu0ix3k" }, "x-examples": { "Example 1": { "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123", "tokenize": "true", "coft_consent": "true" } } }, "title": "Pay using card number - pan", "properties": { "number": { "type": "string", "example": "4242420000001234", "pattern": "^[0-9]{16}$", "description": "Card number" }, "expiry_month": { "type": "string", "example": "02", "description": "Card expiry month in MM format" }, "expiry_year": { "type": "string", "example": "2029", "description": "Card expiry year in YYYY format" }, "holder_name": { "type": "string", "example": "John Doe", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" }, "cvv": { "type": "string", "example": "123", "description": "Card cvv value" }, "tokenize": { "type": "string", "enum": [ "true" ], "description": "If the card is required to be tokenized then, the value is true" }, "coft_consent": { "type": "string", "enum": [ "true" ], "description": "Fixed value as true, confirming the card holder consent to tokenize the card" } }, "required": [ "number", "expiry_month", "expiry_year", "cvv" ] }, { "type": "object", "x-stoplight": { "id": "ze1cvmk9lawl5" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using network token", "properties": { "network_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "network_token", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "605rgi2ucynyf" }, "x-examples": { "Example 1": { "card": { "issuer_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using issuer token", "properties": { "issuer_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP in the ‘Detokenize’ response", "example": "/1234AAASMuXoH8AmYMoglY1234=", "pattern": "^[a-zA-Z0-9\\\\\\\\/\\\\\\\\!@#\\\\\\\\$%\\\\\\\\^&\\\\\\\\*\\\\\\\\(\\\\\\\\)\\\\\\\\{\\\\\\\\}_\\\\\\\\+\\\\\\\\=\\\\\\\\|:”;’,\\\\\\\\.~`\\\\\\\\-\\\\\\\\\\\\\\\\]{1,256}$" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe" } }, "required": [ "issuer_token", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "dbr5tekgwo4lq" }, "x-examples": { "Example 1": { "card": { "cardaccountid": "CA0AAEF9000000000123", "cvv": "123", "card_end": "0055", "holder_name": "John Doe" } } }, "title": "Pay using card account id", "properties": { "cardaccountid": { "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "example": "CA0AAEF9000000000123" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "holder_name": { "type": "string", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe", "description": "Cardholder name" } }, "required": [ "cardaccountid", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "77jgo8f9g4srj" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using alt id token", "properties": { "altid_token": { "type": "object", "required": [ "altid_value", "altid_cryptogram", "altid_expiry_month", "altid_expiry_year" ], "properties": { "altid_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "altid_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "altid_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "altid_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" }, "altid_trid": { "type": "string", "description": "conditional: required only for AMEX - validate once" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "altid_token", "cvv", "holder_name" ] } ] }, "customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "avs": { "type": "object", "x-examples": { "Example 1": { "bankaccount": [ { "number": "12233445566", "ifsc": "IDBK10000002", "name": "John Doe" }, { "number": "12233445567", "ifsc": "IDBK10000002", "name": "John Doe" } ] } }, "description": "This API can be used to verify the bank account number by initiating a penny drop to the account. For upi, validation is done at acquiring bank end ", "title": "Account validation", "properties": { "bankaccounts": { "type": "array", "items": { "type": "object", "properties": { "number": { "description": "Customer's bank account number", "title": "bankacc_number", "x-stoplight": { "id": "9nwo0pwlz0qos" }, "type": "string", "pattern": "^\\\\d{9,18}$", "example": "12233445566" }, "ifsc": { "description": "IFSC of the bank account number", "title": "IFSC", "x-stoplight": { "id": "grn65kr3i0pk0" }, "type": "string", "pattern": "^[A-Za-z]{4}[a-zA-Z0-9]{7}$", "example": "IDBK10000002" }, "name": { "description": "Name of the bank account holder", "title": "bankaccount_holder_name", "x-stoplight": { "id": "jedjceugzit8g" }, "type": "string", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$" } }, "required": [ "number", "ifsc" ] } } } }, "mandate": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "customer_refid": "CUST614514520010012", "subscription_refid": "SUB614514510012", "subscription_desc": "Unlimited Plan", "start_date": "2023-02-08", "end_date": "2050-12-22", "amount": "774.00", "currency": "356", "frequency": "adho", "amount_type": "max" } }, "properties": { "mercid": { "type": "string", "description": "Unique identifier as defined by BillDesk for each merchant", "example": "BDMERCID", "pattern": "^[A-Za-z0-9]{1,10}$" }, "customer_refid": { "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CUSTREF00A00011" }, "subscription_refid": { "type": "string", "description": "Unique reference assigned by merchant for the subscription", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "SUBREF00A00011" }, "subscription_desc": { "type": "string", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "amount": { "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "200.28" }, "currency": { "type": "string", "description": "ISO currency code for the amount, with a value 356 for INR", "example": "356" }, "frequency": { "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n\n•\tweek - weekly\n•\tmnth - monthly\n•\tbimn – bi-monthly\n•\tqurt - quarterly\n•\tbian – bi-annually\n•\tyear - yearly\n•\tadho – adhoc\n\n", "enum": [ "mnth", "week", "bimn", "qurt", "bian", "year", "adho" ], "example": "adho" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] } }, "required": [ "mercid", "customer_refid", "subscription_refid", "subscription_desc", "start_date", "end_date", "amount", "currency", "frequency", "amount_type" ] }, "upi": { "type": "object", "x-stoplight": { "id": "5964437f54f97" }, "x-examples": { "Example 1": { "vpa": "testvpa@abc" } }, "properties": { "vpa": { "type": "string", "description": "Virtual Payment Address", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\\\.\\\\-\\\\_]{2,38}\\\\@[a-zA-Z0-9]{3,20}$", "example": "abc@okbank" } }, "description": "Required when payment_method_type = upi and txn_process_type = collect" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } }, "required": [ "mercid", "orderid", "amount", "currency", "ru", "authentication_type", "3ds_parameter", "txn_process_type", "itemcode", "device", "payment_method_type", "card" ] }, "examples": { "Coupled - One-time payment": { "value": { "mercid": "BDMERCID", "orderid": "CTXN2630942894", "amount": "200.00", "currency": "356", "itemcode": "DIRECT", "ru": "https://www.testmerchant.com/abcpag", "payment_method_type": "card", "txn_process_type": "3ds", "authentication_type": "3ds2", "3ds_parameter": "merchant", "card": { "number": "4000000000000002", "expiry_month": "12", "expiry_year": "2029", "holder_name": "TEST", "cvv": "123" }, "device": { "init_channel": "internet", "ip": "23.3.5.33", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,imageavif,image/webp,image/apng,*/*;q=0.8,application/signedexchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "Coupled - One time payment using network token": { "value": { "mercid": "BDMERCID", "orderid": "ORDER010", "amount": "1.00", "currency": "356", "ru": "https://www.billdesk.com", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "125.10.10.10", "user_agent": "vdsljcnslcdsschdoccdljd", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signedexchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/wAAAAAAgeJDpKQAmYMog1MAAAA=", "token_expiry_month": "06", "token_expiry_year": "2028" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" }, "customer_refid": "123456", "txn_process_type": "3ds", "authentication_type": "3ds2", "3ds_parameter": "merchant" } }, "Coupled - One time payment using issuer token": { "value": { "mercid": "BDMERCID", "orderid": "ORDERID14032023002", "amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "authentication_type": "3ds2", "3ds_parameter": "merchant", "txn_process_type": "3ds", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.2", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "card": { "issuer_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "Coupled - One time payment using card account id": { "value": { "mercid": "BDMERCID", "orderid": "ORDERID14032023002", "amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "authentication_type": "3ds2", "3ds_parameter": "merchant", "txn_process_type": "3ds", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.2", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "card": { "cardaccountid": "CA0AAEF9000000000123", "card_end": "0055", "cvv": "123", "holder_name": "John Doe" } } }, "Coupled - One-time payment with token provisioning (card)": { "value": { "mercid": "BDMERCID", "orderid": "ORDERID14032023006", "amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "authentication_type": "3ds2", "3ds_parameter": "merchant", "txn_process_type": "3ds", "customer_ref_id": "COFT000001", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.2", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "card": { "number": "5400000000000005", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123", "tokenize": "true", "coft_consent": "true" } } }, "Coupled - One-time payment + Mandate set up": { "value": { "mercid": "BDMERCID", "orderid": "ORDERID14032023009", "amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "authentication_type": "3ds2", "3ds_parameter": "merchant", "txn_process_type": "3ds", "customer_ref_id": "COFT000001", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.2", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "mandate": { "mercid": "BDMERCID", "customer_refid": "CUST614514520010012", "subscription_refid": "SUB614514510012", "subscription_desc": "Unlimited Plan", "start_date": "2023-03-14", "end_date": "2050-12-22", "amount": "774.00", "currency": "356", "frequency": "adho", "amount_type": "max" }, "card": { "number": "5400000000000005", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123", "tokenize": "true", "coft_consent": "true" } } }, "Coupled - Recurring payment or subsequent charge for a mandate": { "value": { "mercid": "BDMERCID", "orderid": "RECOR160510002", "amount": "500.00", "currency": "356", "itemcode": "DIRECT", "customer": { "first_name": "John", "last_name": "Doe", "mobile": "9999955555", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" }, "mandateid": "MA061B00045154", "invoice_id": "IA0BF700003662", "subscription_refid": "SUBS11022021", "txn_process_type": "si" } }, "Coupled - One-time payment + Mandate set up without Tokenize": { "value": { "mercid": "BDMERCID", "orderid": "ORDERID14032023009", "amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "authentication_type": "3ds2", "3ds_parameter": "merchant", "txn_process_type": "3ds", "customer_ref_id": "COFT000001", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.2", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "payment_method_type": "card", "mandate": { "mercid": "BDMERCID", "customer_refid": "CUST614514520010012", "subscription_refid": "SUB614514510012", "subscription_desc": "Unlimited Plan", "start_date": "2023-03-14", "end_date": "2050-12-22", "amount": "774.00", "currency": "356", "frequency": "adho", "amount_type": "max" }, "card": { "number": "5400000000000005", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123" } } }, "Decoupled - One-time payment": { "value": { "mercid": "BDMERCID", "orderid": "UAT1541151862", "amount": "1.00", "currency": "356", "bankid": "CY6", "ru": "https://www.someurl.com/", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.1", "user_agent": "Mozilla/5.0" }, "payment_method_type": "card", "card": { "number": "5546xxxxxxxx4183", "expiry_month": "xx", "expiry_year": "xxxx", "holder_name": "Manoj", "cvv": "xxx" }, "txn_process_type": "y3ds", "authentication_data": { "eci": "02", "cavv": "kBMru7SWNjwKhwPoVVBV98AhO2bl", "threeds_version": "2.2.0", "ds_transaction_id": "f3e51b47-4568-4400-a1a7-ec99d1786213" } } }, "Decoupled - One-time AFA payment with token provisioning (card)": { "value": { "mercid": "BDMERCID", "orderid": "UAT6952283919", "amount": "10.00", "currency": "356", "ru": "https://www.someurl.com/", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.1", "user_agent": "Mozilla/5.0" }, "payment_method_type": "card", "customer_refid": "6952283919", "card": { "number": "5546xxxxxxxx4183", "expiry_month": "xx", "expiry_year": "xxxx", "holder_name": "Manoj", "cvv": "xxx" }, "txn_process_type": "y3ds", "authentication_data": { "eci": "05", "cavv": "kBNzPPZW669hkQDIVVA82PYv1b1X", "threeds_version": "2.2.0", "ds_transaction_id": "dbca9dd6-c92d-4b1f-ad76-bf2a16e98956" }, "mandate": { "mercid": "BDMERCID", "customer_refid": "MAN6952283919", "subscription_refid": "SRID6952283919", "subscription_desc": "MonthySubscription", "start_date": "2024-03-19", "end_date": "2024-04-15", "amount": "10.00", "currency": "356", "frequency": "adho", "amount_type": "max" } } }, "Decoupled - One-time AFA payment + Mandate set up - y3ds": { "value": { "mercid": "BDMERCID", "orderid": "UAT6952283919", "amount": "10.00", "currency": "356", "ru": "https://www.someurl.com/", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.1", "user_agent": "Mozilla/5.0" }, "payment_method_type": "card", "customer_refid": "6952283919", "card": { "number": "5546xxxxxxxx4183", "expiry_month": "xx", "expiry_year": "xxxx", "holder_name": "Manoj", "cvv": "xxx" }, "txn_process_type": "y3ds", "authentication_data": { "eci": "05", "cavv": "kBNzPPZW669hkQDIVVA82DYpHv1X", "threeds_version": "2.2.0", "ds_transaction_id": "dbca9dd6-c92d-4b1f-ad76-bf2a16e989037" }, "mandate": { "mercid": "BDMERCID", "customer_refid": "MAN6952283919", "subscription_refid": "SRID6952283919", "subscription_desc": "MonthySubscription", "start_date": "2024-03-19", "end_date": "2024-04-15", "amount": "10.00", "currency": "356", "frequency": "adho", "amount_type": "max" } } }, "Decoupled - One-time payment + Mandate set up without Tokenize": { "value": { "mercid": "BDMERCID", "orderid": "UAT8345399028", "amount": "10.00", "currency": "356", "ru": "https://www.someurl.com/", "itemcode": "DIRECT", "device": { "init_channel": "internet", "ip": "124.124.1.1", "user_agent": "Mozilla/5.0" }, "payment_method_type": "card", "customer_refid": "8345399028", "card": { "number": "5546xxxxxxxx4183", "expiry_month": "xx", "expiry_year": "xxxx", "holder_name": "Manoj", "cvv": "xxx", "tokenize": "true", "coft_consent": "true" }, "txn_process_type": "y3ds", "authentication_data": { "eci": "05", "cavv": "kBNzPPZW669hkQDIVVA82DVpyH1x", "threeds_version": "2.2.0", "ds_transaction_id": "dbca9dd6-c92d-4b1f-ad76-bf2a16e97857" }, "mandate": { "mercid": "BDMERCID", "customer_refid": "MAN8345399028", "subscription_refid": "SRID8345399028", "subscription_desc": "MonthySubscription", "start_date": "2024-03-19", "end_date": "2024-04-15", "amount": "10.00", "currency": "356", "frequency": "adho", "amount_type": "max" } } } } } } }, "tags": [ "Transaction" ] } }, "/payments/ve1_2/transactions/update": { "post": { "summary": "Update Transaction", "description": "This endpoint authorizes an existing transaction.", "operationId": "updateTransaction", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "transactionid": "X4560477641875", "response_parameters": { "AccuResponseCode": "ACCU000", "session": "X4440639244491", "AccuGuid": "a13df076-5c82-4fbf-aa5c-be11e9847e9a", "AccuRequestId": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==" }, "payment_method_type": "card", "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "holder_name": "John Doe" } } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "response_parameters": { "type": "object", "x-examples": { "Example 1": { "cres": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g", "AccuResponseCode": "ACCU000", "session": "X4440639244491", "AccuGuid": "a13df076-5c82-4fbf-aa5c-be11e9847e9a", "AccuRequestId": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==", "MD": "", "Pares": "" } }, "properties": { "cres": { "type": "string", "description": "Response parameters as received from the issuer, and will be cres for 3ds 2.0 flow", "example": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g" }, "AccuResponseCode": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "ACCU000 " }, "session": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "X4440639244491" }, "AccuGuid": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "a13df076-5c82-4fbf-aa5c-be11e9847e9a" }, "AccuRequestId": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==\"" }, "otp": { "type": "string", "description": "for a native authentication where next_step = capture_otp" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "card": { "oneOf": [ { "type": "object", "x-stoplight": { "id": "1xxgnveu0ix3k" }, "x-examples": { "Example 1": { "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123", "tokenize": "true", "coft_consent": "true" } } }, "title": "Pay using card number - pan", "properties": { "number": { "type": "string", "example": "4242420000001234", "pattern": "^[0-9]{16}$", "description": "Card number" }, "expiry_month": { "type": "string", "example": "02", "description": "Card expiry month in MM format" }, "expiry_year": { "type": "string", "example": "2029", "description": "Card expiry year in YYYY format" }, "holder_name": { "type": "string", "example": "John Doe", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" }, "cvv": { "type": "string", "example": "123", "description": "Card cvv value" }, "tokenize": { "type": "string", "enum": [ "true" ], "description": "If the card is required to be tokenized then, the value is true" }, "coft_consent": { "type": "string", "enum": [ "true" ], "description": "Fixed value as true, confirming the card holder consent to tokenize the card" } }, "required": [ "number", "expiry_month", "expiry_year", "cvv" ] }, { "type": "object", "x-stoplight": { "id": "ze1cvmk9lawl5" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using network token", "properties": { "network_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "network_token", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "605rgi2ucynyf" }, "x-examples": { "Example 1": { "card": { "issuer_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using issuer token", "properties": { "issuer_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP in the ‘Detokenize’ response", "example": "/1234AAASMuXoH8AmYMoglY1234=", "pattern": "^[a-zA-Z0-9\\\\\\\\/\\\\\\\\!@#\\\\\\\\$%\\\\\\\\^&\\\\\\\\*\\\\\\\\(\\\\\\\\)\\\\\\\\{\\\\\\\\}_\\\\\\\\+\\\\\\\\=\\\\\\\\|:”;’,\\\\\\\\.~`\\\\\\\\-\\\\\\\\\\\\\\\\]{1,256}$" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe" } }, "required": [ "issuer_token", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "dbr5tekgwo4lq" }, "x-examples": { "Example 1": { "card": { "cardaccountid": "CA0AAEF9000000000123", "cvv": "123", "card_end": "0055", "holder_name": "John Doe" } } }, "title": "Pay using card account id", "properties": { "cardaccountid": { "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "example": "CA0AAEF9000000000123" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "holder_name": { "type": "string", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe", "description": "Cardholder name" } }, "required": [ "cardaccountid", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "77jgo8f9g4srj" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using alt id token", "properties": { "altid_token": { "type": "object", "required": [ "altid_value", "altid_cryptogram", "altid_expiry_month", "altid_expiry_year" ], "properties": { "altid_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "altid_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "altid_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "altid_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" }, "altid_trid": { "type": "string", "description": "conditional: required only for AMEX - validate once" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "altid_token", "cvv", "holder_name" ] } ] }, "mandateid": { "title": "mandateid", "x-stoplight": { "id": "joq1b0hwy6hce" }, "type": "string", "description": "Unique mandateid created by BillDesk", "pattern": "^[A-Za-z0-9]{1,20}$", "example": "MA19E400049927" } }, "required": [ "mercid", "transactionid", "response_parameters", "payment_method_type", "card" ] }, "examples": { "One-time payment": { "value": { "mercid": "BDMERCID", "transactionid": "X4560477641875", "response_parameters": { "cres": "eJytmVnTosjSgO/5FR19Lo0eVgUm7PdEsSOLoOx3bLKDCgry6w/qdE/PTJ+I/k583AhZVFZWZmUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==" }, "payment_method_type": "card", "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "holder_name": "John Doe" } } }, "One-time payment for rupay redirect": { "value": { "mercid": "BDMERCID", "transactionid": "U4560001099939", "response_parameters": { "AccuResponseCode": "ACCU000", "session": "X4440639244491", "AccuGuid": "a13df076-5c82-4fbf-aa5c-be11e9847e9a", "AccuRequestId": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==\"" }, "payment_method_type": "card", "card": { "card": { "number": "4242420000001234", "expiry_month": "02", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123" } } } }, "One-time payment for rupay OTP": { "value": { "mercid": "BDMERCID", "transactionid": "U4560001099939", "response_parameters": { "otp": "123456" }, "payment_method_type": "card", "card": { "card": { "number": "4242420000001234", "expiry_month": "02", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123" } } } }, "One-time payment + Mandate set up ": { "value": { "mercid": "BDMERCID", "transactionid": "X4560477641875", "mandateid": "MA1DE900088018", "response_parameters": { "cres": "eJytmVnTosjSgO/5FR19Lo0eVgUm7PdEsSOLoOx3bLKDCgry6w/qdE/PTJ+I/k583AhZVFZWZmUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==" }, "payment_method_type": "card", "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "holder_name": "John Doe" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "transaction", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "517606", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "517606", "eci": "05", "payment_method_type": "card", "card": { "type": "CREDIT", "card_end": "123", "network": "VISA", "issuer": "ABC Bank" } } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "surcharge": { "title": "surcharge", "x-stoplight": { "id": "u8bi4pr2xista" }, "type": "string", "description": "Customer surcharge in two decimals applied to the transaction amount, if any" }, "discount": { "title": "discount", "x-stoplight": { "id": "0dgp8etm5709j" }, "type": "string", "description": "Customer discount in two decimals applied to the transaction amount, if any" }, "charge_amount": { "title": "charge_amount", "x-stoplight": { "id": "m2z4sf48a8a5w" }, "type": "string", "description": "Total charge to the customer" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "auth_status": { "title": "auth_status", "x-stoplight": { "id": "35i21snltcrdq" }, "type": "string", "description": "Represents the authorization status of the transaction with the following possible values:\n•\t0300 - transaction is successful\n•\t0002 - transaction is pending for authorization\n•\t0399 - transaction failed", "enum": [ "0300", "0002", "0399" ] }, "transaction_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "transaction_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "transaction_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "eci": { "title": "eci", "x-stoplight": { "id": "jq2g7i098vu5j" }, "type": "string", "description": "Authentication ECI indicator, as per the 3ds protocol (for V, M, D, A cards)" }, "authcode": { "title": "authcode", "x-stoplight": { "id": "a760wo51p1b9k" }, "type": "string", "description": "Authorization code received from the acquirer for a successfully authorized card transaction" }, "bank_ref_no": { "title": "bank_ref_no", "x-stoplight": { "id": "tls0w5ung6eha" }, "type": "string", "description": "Transaction reference number generated by bank or acquirer " }, "card": { "type": "object", "x-stoplight": { "id": "n1nmwdiqy5hrc" }, "x-examples": { "Example 1": { "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" } } }, "properties": { "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Last 4 digits of the card number \nNote: For an EMI transaction via network token, this attribute value is required for loan booking", "example": "xxxxxxxxxxxx1001" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card network, for eg. visa", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" } } }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "mandate": { "type": "object", "properties": { "objectid": { "type": "string" }, "mercid": { "type": "string" }, "customer_refid": { "type": "string" }, "subscription_refid": { "type": "string" }, "subscription_desc": { "type": "string" }, "amount": { "type": "string" }, "amount_type": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "frequency": { "type": "string" }, "payment_method_type": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "mandateid": { "type": "string" }, "createdon": { "type": "string" }, "verification_error_code": { "type": "string" }, "verification_error_type": { "type": "string" }, "verification_error_desc": { "type": "string" } }, "x-examples": { "Example 1": { "objectid": "mandate", "mercid": "BDMERCID", "customer_refid": "CUSTREF00A00011", "subscription_refid": "SUBREF00A00011", "subscription_desc": "Family Plan", "amount": "1500.00", "amount_type": "maximum", "start_date": "2021-05-16", "end_date": "2029-10-22", "frequency": "adho", "payment_method_type": "card", "currency": "356", "status": "pending", "mandateid": "MA0DDD00050243", "createdon": "2021-05-16T18:23:11+05:30", "verification_error_code": "TRS0000", "verification_error_type": "success", "verification_error_desc": "Transaction Successful" } } }, "payment_category": { "title": "payment_category", "x-stoplight": { "id": "epd66eokga23s" }, "type": "string", "description": "Payment Category Code, defines the transaction belonging to the payment mode.\n• 00 - Card Gateway\n• 01 - Netbanking\n• 02 - Credit card\n• 03 - Debit card\n• 04 - Cash card\n• 05 - Mobile wallet\n• 10 - UPI\n• 11 - Bharat QR\n• 12 - Loan EMI\n• 13 - NEFT\n• 18 - UPI Credit\n• 19 - ENACH\n• 20 - CBDC\n• 21 - UPI Prepaid Wallet\n• 22 - UPI Credit Line", "example": "18" }, "me_ref_id": { "title": "me_ref_id", "x-stoplight": { "id": "5gfw31bjgpf6x" }, "type": "string", "description": "Unique identifier for a merchant, defined by the acquiring bank as a 6 digit code", "example": "545963" } } }, "examples": { "One-time payment for 3ds 2.0": { "value": { "objectid": "transaction", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "517606", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "517606", "eci": "05", "payment_method_type": "card", "card": { "type": "CREDIT", "card_end": "123", "network": "VISA", "issuer": "ABC Bank" } } }, "One-time payment for Rupay redirect flow": { "value": { "objectid": "authentication", "mercid": "BDMERCID", "transactionid": "string", "orderid": "TEST0000009005", "transaction_date": "2019-08-24T14:15:22Z", "amount": "299.28", "surcharge": "0.00", "discount": "0.00", "charge_amount": "299.28", "currency": "356", "ru": "https://www.merchant.com", "txn_process_type": "y3ds", "bankid": "1HM", "itemcode": "DIRECT", "payment_method_type": "card", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "517606", "eci": "05", "card": { "type": "CREDIT", "card_end": "123", "network": "RUPAY", "issuer": "ABC Bank" } } }, "One-time payment for Rupay OTP flow": { "value": { "objectid": "transaction", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "517606", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "517606", "eci": "05", "payment_method_type": "card", "card": { "type": "CREDIT", "card_end": "123", "network": "RUPAY", "issuer": "ABC Bank" } } }, "One-time payment + Mandate set up ": { "value": { "objectid": "transaction", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "mandate": { "objectid": "mandate", "mercid": "BDMERCID", "customer_refid": "CUST61451452001", "subscription_refid": "SUB61451452001", "subscription_desc": "Unlimited Plan", "amount": "500.00", "amount_type": "maximum", "start_date": "2022-03-30", "end_date": "2050-12-22", "frequency": "adho", "payment_method_type": "card", "currency": "356", "status": "active", "mandateid": "MA1DE900088018", "createdon": "2022-03-30T00:41:29+05:30", "verification_error_code": "TRS0000", "verification_error_type": "success", "verification_error_desc": "Transaction Successful" }, "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "517606", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "517606", "eci": "05", "payment_method_type": "card", "card": { "objectid": "card", "masked_value": "xxxxxxxxxxxx6633", "type": "CREDIT", "card_end": "6633", "network": "VISA", "issuer": "RBL Bank", "cardaccountid": "CA07BBAA000012341234", "coft_consent": "true", "cardaccount": { "objectid": "cardaccount", "mercid": "BDMERCID", "customer_refid": "CUSREF00000001", "cardaccountid": "CA07D151000000001234", "orderid": "ODR000000001", "masked_value": "xxxxxxxxxxxx1234", "holder_name": "John Doe", "issuer": "ABC Bank", "network": "VISA", "status": "ACTIVE", "coft_consent": "true", "createdon": "2022-03-20T21:53:50+05:30", "network_token": { "token_ref_no": "1fa3dbc43247ac3092971d3f8f4e658f", "status": "ACTIVE", "createdon": "2022-03-20T21:53:50+05:30", "token_expiry_month": "12", "token_expiry_year": "2030" } } } } }, "One-time AFA payment + Token Provision": { "value": { "objectid": "transaction", "transactionid": "U4560000738803", "orderid": "OID1767041032", "mercid": "BDMERCID", "transaction_date": "2023-12-05T15:46:02+05:30", "amount": "2.00", "surcharge": "3.00", "discount": "0.00", "charge_amount": "5.00", "currency": "356", "ru": "https://merchant.com", "txn_process_type": "3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "W2MMZTYUJ1", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxxxxxx", "type": "CREDIT", "card_end": "0002", "network": "VISA", "issuer": "SBI", "cardaccountid": "CA0F15D400000000913A", "coft_consent": "true", "cardaccount": { "cardaccountid": "CA0F15D400000000913A", "objectid": "cardaccount", "customer_refid": "CUST7686", "cardaccount_status": "ACTIVE", "coft_consent": "true", "createdon": "2023-12-05T15:45:21+0530", "network_token": { "token_ref_no": "400000z1-7766-2by8-c37x-55d46w9a1234", "status": "ACTIVE", "token_expiry_month": "12", "token_expiry_year": "2029" } } }, "payment_category": "02" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Default error": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "tags": [ "Transaction" ] } }, "/payments/ve1_2/transactions/get": { "post": { "summary": "Retrieve Transaction", "operationId": "post-payments-v1_2-transactions-get", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "transaction", "transactionid": "X7890733918355", "orderid": "TST01092022004", "mercid": "BDMERCID", "transaction_date": "2022-09-01T00:38:25+05:30", "amount": "5.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "5.00", "currency": "356", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "txn_process_type": "collect", "bankid": "789", "itemcode": "DIRECT", "bank_ref_no": "224457208022", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "upi", "refundInfo": [ { "refundid": "X78907339183552", "refund_amount": "3.00", "currency": "356", "refund_date": "2022-09-01T00:40:06+05:30", "merc_refund_ref_no": "REFUNDREF0003", "refund_status": "0799" }, { "refundid": "X78907339183551", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-09-01T00:40:00+05:30", "merc_refund_ref_no": "REFUNDREF0002", "refund_status": "0799" } ] } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "surcharge": { "title": "surcharge", "x-stoplight": { "id": "u8bi4pr2xista" }, "type": "string", "description": "Customer surcharge in two decimals applied to the transaction amount, if any" }, "discount": { "title": "discount", "x-stoplight": { "id": "0dgp8etm5709j" }, "type": "string", "description": "Customer discount in two decimals applied to the transaction amount, if any" }, "charge_amount": { "title": "charge_amount", "x-stoplight": { "id": "m2z4sf48a8a5w" }, "type": "string", "description": "Total charge to the customer" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "bank_ref_no": { "title": "bank_ref_no", "x-stoplight": { "id": "tls0w5ung6eha" }, "type": "string", "description": "Transaction reference number generated by bank or acquirer " }, "auth_status": { "title": "auth_status", "x-stoplight": { "id": "35i21snltcrdq" }, "type": "string", "description": "Represents the authorization status of the transaction with the following possible values:\n•\t0300 - transaction is successful\n•\t0002 - transaction is pending for authorization\n•\t0399 - transaction failed", "enum": [ "0300", "0002", "0399" ] }, "transaction_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "transaction_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "transaction_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "refundInfo": { "type": "object", "x-stoplight": { "id": "0a9154jkzqr2x" }, "properties": { "refundInfo": { "type": "array", "items": { "type": "object", "properties": { "refundid": { "type": "string", "description": "Unique id generated by BillDesk for the refund" }, "refund_amount": { "type": "string", "description": "Refund amount in two decimals" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "refund_date": { "type": "string", "description": "BillDesk refund date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "merc_refund_ref_no": { "type": "string", "description": "Unique reference number generated by the merchant for the refund request" }, "refund_status": { "type": "string", "description": "Represents the refund status with the following values:\n•\t0799 – categorized as a refund, where the original transaction has been already settled \n•\t0699 – categorized as a cancellation, where the original transaction has not been settled\n" } } } } }, "description": "" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "split_payment": { "type": "object", "x-examples": { "Example 1": { "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split payment amount will be settled.", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID" }, "amount": { "type": "string", "description": "Split Amount which is settled in the respective Split Merchant ID.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" } }, "description": "This object is applicable in case a merchant has opted to receive the settlement in multiple settlement accounts", "title": "split_payment_request" }, "payment_category": { "title": "payment_category", "x-stoplight": { "id": "epd66eokga23s" }, "type": "string", "description": "Payment Category Code, defines the transaction belonging to the payment mode.\n• 00 - Card Gateway\n• 01 - Netbanking\n• 02 - Credit card\n• 03 - Debit card\n• 04 - Cash card\n• 05 - Mobile wallet\n• 10 - UPI\n• 11 - Bharat QR\n• 12 - Loan EMI\n• 13 - NEFT\n• 18 - UPI Credit\n• 19 - ENACH\n• 20 - CBDC\n• 21 - UPI Prepaid Wallet\n• 22 - UPI Credit Line", "example": "18" }, "me_ref_id": { "title": "me_ref_id", "x-stoplight": { "id": "5gfw31bjgpf6x" }, "type": "string", "description": "Unique identifier for a merchant, defined by the acquiring bank as a 6 digit code", "example": "545963" } } }, "examples": { "Without refund details": { "value": { "objectid": "transaction", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "ru": "https://www.merchanturl.com/response.jsp", "txn_process_type": "3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "517606", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "authcode": "517606", "eci": "05", "payment_method_type": "card", "card": { "type": "CREDIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" } } }, "with refund details": { "value": { "objectid": "transaction", "transactionid": "X7890733918355", "orderid": "TST01092022004", "mercid": "BDMERCID", "transaction_date": "2022-09-01T00:38:25+05:30", "amount": "5.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "5.00", "currency": "356", "txn_process_type": "collect", "bankid": "789", "itemcode": "DIRECT", "bank_ref_no": "224457208022", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "upi", "refundInfo": [ { "refundid": "X78907339183552", "refund_amount": "3.00", "currency": "356", "refund_date": "2022-09-01T00:40:06+05:30", "merc_refund_ref_no": "REFUNDREF0003", "refund_status": "0799" }, { "refundid": "X78907339183551", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-09-01T00:40:00+05:30", "merc_refund_ref_no": "REFUNDREF0002", "refund_status": "0799" } ] } }, "With split payment": { "value": { "objectid": "transaction", "transactionid": "X7890733918355", "orderid": "TST01092022004", "mercid": "BDMERCID", "transaction_date": "2022-09-01T00:38:25+05:30", "amount": "4000.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "4000.00", "currency": "356", "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ], "txn_process_type": "collect", "bankid": "789", "itemcode": "DIRECT", "bank_ref_no": "224457208022", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "upi", "refundInfo": [ { "refundid": "X78907339183552", "refund_amount": "3.00", "currency": "356", "refund_date": "2022-09-01T00:40:06+05:30", "merc_refund_ref_no": "REFUNDREF0003", "refund_status": "0799" }, { "refundid": "X78907339183551", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-09-01T00:40:00+05:30", "merc_refund_ref_no": "REFUNDREF0002", "refund_status": "0799" } ] } }, "With Tokenization": { "value": { "mercid": "BDMERCID", "objectid": "transaction", "transactionid": "X7890733918355", "orderid": "TEST0000009005", "transaction_date": "2019-08-24T14:15:22Z", "amount": "299.28", "surcharge": "0.00", "discount": "0.00", "charge_amount": "299.28", "currency": "356", "txn_process_type": "y3ds", "bankid": "456", "itemcode": "DIRECT", "bank_ref_no": "123456", "auth_status": "0300", "transaction_error_code": "TRS0000", "transaction_error_desc": "Transaction Successful", "transaction_error_type": "success", "payment_method_type": "card", "card": { "masked_value": "xxxxxxxxxxxxxxxx", "type": "CREDIT", "card_end": "0002", "network": "VISA", "issuer": "SBI", "cardaccountid": "CA0F15D400000000913A", "coft_consent": "true", "cardaccount": { "cardaccountid": "CA0F15D400000000913A", "objectid": "cardaccount", "customer_refid": "CUST7686", "cardaccount_status": "ACTIVE", "coft_consent": "true", "createdon": "2023-12-05T15:45:21+0530", "network_token": { "token_ref_no": "400000z1-7766-2by8-c37x-55d46w9a1234", "status": "ACTIVE", "token_expiry_month": "12", "token_expiry_year": "2029" } } }, "payment_category": "18", "me_ref_id": "545963" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "description": "Merchant can retrieve the transaction either by using mercid and orderid or the mercid and the transactionid.", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "orderid": "TST01092022004", "transactionid": "X4560477641875", "refund_details": "true" } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "refund_details": { "description": "Boolean value that should be provided as true to retrieve the refund information associated with transaction", "type": "string", "enum": [ "true" ] } }, "required": [ "mercid" ] }, "examples": { "Using orderid": { "value": { "mercid": "BDMERCID", "orderid": "ORDER202200000001" } }, "Using orderid & refund details": { "value": { "orderid": "TST01092022004", "mercid": "BDMERCID", "refund_details": "true" } }, "Using transactionid": { "value": { "mercid": "BDMERCID", "transactionid": "X4560477641875" } } } } } }, "tags": [ "Transaction" ] } }, "/payments/ve1_2/refunds/create": { "post": { "summary": "Create Refund", "operationId": "createRefund", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "refund", "refundid": "X45604776418751", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "2.00", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-03-20T21:27:47+05:30", "merc_refund_ref_no": "REFTS14RTEST001", "refund_status": "0799" } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "refundid": { "type": "string", "description": "Unique refundid created by BillDesk for each refund request", "pattern": "^[A-Za-z0-9]{1,15}$", "example": "X45604776418751" }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "txn_amount": { "type": "string", "description": "Original transaction amount in two decimals", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "2400.00" }, "refund_amount": { "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "1100.00", "description": "Refund amount in two decimals" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "refund_date": { "type": "string", "description": "BillDesk refund date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time" }, "merc_refund_ref_no": { "type": "string", "pattern": "^[A-Za-z0-9\\_\\:\\-]{1,100}$", "description": "Unique reference number created by the merchant for the refund request", "example": "REFTS14RTEST001" }, "split_payment": { "type": "object", "x-examples": { "Example 1": { "split_refund": [ { "mercid": "BDMERCID1", "txn_amount": "75.00", "refund_amount": "65.00", "refund_status": "0799" }, { "mercid": "BDMERCID2", "txn_amount": "25.00", "refund_amount": "25.00", "refund_status": "0699" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split refund amount will be adjusted" }, "txn_amount": { "type": "string", "description": "Split Amount which was settled in the respective Split Merchant ID." }, "refund_amount": { "type": "string", "description": "Refund Amount against txn_amount." }, "refund_status": { "type": "string", "description": "Represents the refund status of the transaction with the following possible values:\n•\t0799 - transaction is refunded\n•\t0699 - transaction is cancelled" } }, "description": "" }, "refund_status": { "type": "string", "description": "Represents the refund status with the following values:\n•\t0799 – categorized as a refund, where the original transaction has been already settled \n•\t0699 – categorized as a cancellation, where the original transaction has not been settled", "enum": [ "0699", "0799" ] } } }, "examples": { "Create Refund Response": { "value": { "objectid": "refund", "refundid": "X45604776418751", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "2.00", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-03-20T21:27:47+05:30", "merc_refund_ref_no": "REFTS14RTEST001", "refund_status": "0799" } }, "Create Split Refund Response": { "value": { "objectid": "refund", "refundid": "X45604776418751", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "100.00", "refund_amount": "90.00", "split_refund": [ { "mercid": "BDMERCID1", "txn_amount": "75.00", "refund_amount": "65.00", "refund_status": "0799" }, { "mercid": "BDMERCID2", "txn_amount": "25.00", "refund_amount": "25.00", "refund_status": "0699" } ], "currency": "356", "refund_date": "2022-03- 20T21:27:47+05:30", "merc_refund_ref_no": "REFTS14RTEST001 ", "refund_status": "0799" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Invalid merchant config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "2.00", "refund_amount": "2.00", "currency": "356", "merc_refund_ref_no": "REFTS14RTEST001" } }, "properties": { "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "txn_amount": { "type": "string", "description": "Original transaction amount in two decimals", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "2400.00" }, "refund_amount": { "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "description": "Refund amount in two decimals", "example": "1100.00" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "merc_refund_ref_no": { "type": "string", "description": "Unique reference number created by the merchant for the refund request", "pattern": "^[A-Za-z0-9\\_\\:\\-]{1,100}$", "example": "REFTS14RTEST001" }, "split_payment": { "type": "object", "x-stoplight": { "id": "715c0b8e1f0ab" }, "x-examples": { "Example 1": { "split_refund": [ { "mercid": "BDMERCID1", "txn_amount": "75.00", "refund_amount": "65.00" }, { "mercid": "BDMERCID2", "txn_amount": "25.00", "refund_amount": "25.00" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split refund amount will be adjusted", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID" }, "txn_amount": { "type": "string", "description": "Split Amount which was settled in the respective Split Merchant ID.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" }, "refund_amount": { "type": "string", "description": "Refund Amount against txn_amount.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" } }, "title": "" } }, "required": [ "transactionid", "orderid", "mercid", "transaction_date", "txn_amount", "refund_amount", "currency", "merc_refund_ref_no" ] }, "examples": { "Create Refund": { "value": { "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "2.00", "refund_amount": "2.00", "currency": "356", "merc_refund_ref_no": "REFTS14RTEST001" } }, "Create Split Refund": { "value": { "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "100.00", "refund_amount": "90.00", "split_refund": [ { "mercid": "BDMERCID1", "txn_amount": "75.00", "refund_amount": "65.00" }, { "mercid": "BDMERCID2", "txn_amount": "25.00", "refund_amount": "25.00" } ], "currency": "356", "merc_refund_ref_no": "REFTS14RTEST001" } } } } } }, "description": "A refund can be initiated for a transaction using the Create Refund API. \n\nMultiple refund requests can be initiated against the same transactionid such that the sum of the refund amounts do not exceed the transaction amount.", "tags": [ "Refund" ] } }, "/payments/ve1_2/refunds/get": { "parameters": [], "post": { "summary": "Retrieve Refund", "operationId": "retrieveRefund", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "objectid": "refund", "refundid": "X45604776418751", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "2.00", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-03-20T21:27:47+05:30", "merc_refund_ref_no": "REFTS1000004RTEST001", "refund_status": "0799" } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "refundid": { "type": "string", "description": "Unique refundid created by BillDesk for each refund request", "pattern": "^[A-Za-z0-9]{1,15}$", "example": "X45604776418751" }, "transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "txn_amount": { "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "2400.00", "description": "Original transaction amount in two decimals" }, "refund_amount": { "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "1100.00", "description": "Refund amount in two decimals" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "refund_date": { "type": "string", "format": "date-time", "description": "BillDesk refund date and time in YYYY-MMDDThh:mm:ssTZD format" }, "merc_refund_ref_no": { "type": "string", "pattern": "^[A-Za-z0-9\\_\\:\\-]{1,100}$", "example": "REFTS14RTEST001", "description": "Unique reference number created by the merchant for the refund request" }, "refund_status": { "type": "string", "description": "Represents the refund status with the following values:\n•\t0799 – categorized as a refund, where the original transaction has been already settled \n•\t0699 – categorized as a cancellation, where the original transaction has not been settled", "enum": [ "0699", "0799" ] } } }, "examples": { "Retrieve refund response": { "value": { "objectid": "refund", "refundid": "X45604776418751", "transactionid": "X4560477641875", "orderid": "ORDER202200000001", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:20:07+05:30", "txn_amount": "2.00", "refund_amount": "2.00", "currency": "356", "refund_date": "2022-03-20T21:27:47+05:30", "merc_refund_ref_no": "REFTS1000004RTEST001", "refund_status": "0799" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Invalid merchant config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "description": "Merchant can retrieve refund details either by using mercid and merc_refund_ref_no, or the mercid and refundid.", "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "refundid": "X45604776418751" } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "refundid": { "type": "string", "description": "Unique refundid created by BillDesk for each refund request", "pattern": "^[A-Za-z0-9]{1,15}$", "example": "X45604776418751" }, "merc_refund_ref_no": { "type": "string", "description": "Unique reference number created by the merchant for the refund request", "pattern": "^[A-Za-z0-9\\_\\:\\-]{1,100}$", "example": "REFTS14RTEST001" } }, "required": [ "mercid" ] }, "examples": { "Using BillDesk refundid": { "value": { "mercid": "BDMERCID", "refundid": "X45604776418751" } }, "Using merc_refund_ref_no": { "value": { "mercid": "BDMERCID", "merc_refund_ref_no": "REFTS14RTEST001" } } } } } }, "tags": [ "Refund" ] } }, "/payments/ve1_2/authentications/create": { "post": { "summary": "Create Authentication", "operationId": "createAuthentication", "responses": { "200": { "description": "OK", "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } }, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "links": [ { "href": "https://www.issuerurl.com/page", "rel": "redirect", "method": "post", "parameters": { "valid_till": "2023-02-16T11:43:28+05:30", "creq": "5a7e8901aa256b4f5012355dc4b12f7bb474be6d7f09232639220163cfb1eb7e36ac8594c92379254.70675f706172616d5f656e6333" } } ], "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "X4560643061923", "authentication_date": "2023-02-15T11:43:28+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "456", "payment_method_type": "card", "authentication_type": "3ds2", "authentication_status": "pending", "orderid": "TEST0000009005", "next_step": "3ds2_challenge", "authentication_error_code": "AUP0000", "authentication_error_type": "pending", "authentication_error_desc": "Authentication Pending", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "card": { "masked_value": "xxxxxxxxxxxx1234", "type": "CREDIT", "card_end": "1234", "network": "MASTER", "issuer": "HDFC Bank" } } }, "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "authenticationid": { "title": "authenticationid", "x-stoplight": { "id": "c1hskskz8e2iq" }, "type": "string", "description": "Unique authenticationid created by BillDesk", "pattern": "^[a-zA-Z0-9]{14,35}$", "example": "A1HM0000389872" }, "links": { "type": "object", "x-stoplight": { "id": "7t5udyb6ilh37" }, "x-examples": { "Example 1": { "links": [ { "href": "https://wwww.issuerurl.com/somepage", "rel": "redirect", "method": "post", "parameters": { "creq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIzYjFlYmQ5NC04NTZhLTRlYjEtYTJlMS00MWZkNTdjZGFkZjAiLCJhY3NUcmFuc0lEIjoiOGMzMzk3NTItMjNmMS00NmZlLThmNzEtMzAwZjAyMzY0NjcxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0=" } } ] } }, "description": "Associated links with the object, and contains the issuer URL that will be provided in the redirect authentication workflow", "title": "links", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string", "description": "Issuer response URL" }, "rel": { "type": "string", "description": "Fixed value as redirect" }, "method": { "type": "string", "enum": [ "POST" ] }, "parameters": { "description": "Parameters that are used to redirect the customer to the issuer URL", "type": "object", "x-examples": { "Example 1": { "tranid": "973712065583009734440001099962", "AccuCardholderId": "90926094409", "AccuReturnURL": "https://www.merchanturl.com/response.jsp", "session": "U4440001099962", "AccuGuid": "15e66a3b-956e-42f8-84d4-859e3e8c9fed", "TermUrl": "https://www.merchanturl.com/response.jsp", "AccuRequestId": "YjIxM2ZiZGUyMGY2MmNjZWE5YWQ1NGE5OGNiZDUyZjkyYThlMDFiYjFkMTY1Yjc0ZTI4NTgxNDA1MGRiNzE0Ng==", "cardend": "4938" } }, "title": "parameters", "properties": { "creq": { "type": "string", "description": "Challenge request message or payment message for 3ds2.0 protocol authentication" }, "bdcreq": { "type": "string", "description": "Challenge request message or payment message for \n3ds2.0 protocol authentication (Threeds method url flow)" }, "tranid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuCardholderId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuReturnURL": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "session": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuGuid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuRequestId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } } } } } } }, "authentication_date": { "title": "authentication_date", "x-stoplight": { "id": "uz8duh7gras5w" }, "type": "string", "description": "Authentication date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "authentication_type": { "title": "authentication_type", "x-stoplight": { "id": "c33ke2q5rl7ql" }, "type": "string", "description": "Represents the type of authentication initiated in the request, will be fixed value - 3ds2", "enum": [ "3ds2" ], "example": "3ds2" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "next_step": { "title": "next_step", "x-stoplight": { "id": "ayox9qr52qx6o" }, "type": "string", "description": "Refers to the action to be taken by the merchant, for eg. redirect or capture_otp", "enum": [ "redirect", "capture_otp", "3ds2_challenge", "3ds2_frictionless" ] }, "authentication_status": { "title": "authentication_status", "x-stoplight": { "id": "h2j1d7gkgfr54" }, "type": "string", "description": "Represents the status of the request – with possible values as \n•\tpending\n•\tsuccess\n•\tfailure", "enum": [ "pending", "success", "failure" ] }, "authentication_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "authentication_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "authentication_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "card": { "type": "object", "x-stoplight": { "id": "n1nmwdiqy5hrc" }, "x-examples": { "Example 1": { "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" } } }, "properties": { "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Last 4 digits of the card number \nNote: For an EMI transaction via network token, this attribute value is required for loan booking", "example": "xxxxxxxxxxxx1001" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card network, for eg. visa", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" } } }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "threeds_transaction_id": { "title": "threeds_transaction_id", "x-stoplight": { "id": "c54txyf8e8aqp" }, "type": "string", "description": "Threeds server transaction id", "format": "uuid", "example": "4184a9f8-b0f3-47d2-91ec-bc9939080e32" } } }, "examples": { "Challenge Flow": { "value": { "links": [ { "href": "https://www.issuerurl.com/page", "rel": "redirect", "method": "post", "parameters": { "valid_till": "2023-02-16T11:43:28+05:30", "creq": "5a7e8901aa256b4f5012355dc4b12f7bb474be6d7f09232639220163cfb1eb7e36ac8594c92379254.70675f706172616d5f656e6333" } } ], "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "X4560643061923", "authentication_date": "2023-02-15T11:43:28+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "456", "payment_method_type": "card", "authentication_type": "3ds2", "authentication_status": "pending", "orderid": "TEST0000009005", "next_step": "3ds2_challenge", "authentication_error_code": "AUP0000", "authentication_error_type": "pending", "authentication_error_desc": "Authentication Pending", "card": { "masked_value": "xxxxxxxxxxxx1234", "type": "CREDIT", "card_end": "1234", "network": "MASTER", "issuer": "HDFC Bank" } } }, "Frictionless flow": { "value": { "itemcode": "VDDIRECT", "objectid": "authentication", "authenticationid": "A4560000345048", "authentication_date": "2022-03-27T10:33:01+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "456", "payment_method_type": "card", "authentication_type": "redirect", "authentication_status": "success", "orderid": "27000000001", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" }, "eci": "05", "cavv": "kBMRIy8dy6JsAAAAAAA82DVhvlpQ", "threeds_version": "2.2.0", "ds_transaction_id": "ef8b6d89-639d-4490-9e38-903691a4087a", "threeds_transaction_id": "36041b77-24db-42f1-87a6-dfbd5797110b" } }, "Rupay redirection flow": { "value": { "links": [ { "href": "https://wwww.issuerurl.com/", "rel": "redirect", "method": "POST", "parameters": { "AccuCardholderId": "TEST1091569481988nW0zT6fB", "AccuReturnURL": "https://www.someurl.com/response.jsp", "session": "X4560639244491", "AccuGuid": "123456-5c82-4fbf-aa5c-123456", "TermUrl": "https://www.someurl.com/Response/", "AccuRequestId": "NTNlMWMwNjgzZjkyMzEwMGEA==", "cardend": "1234" } } ], "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "X4560639244491", "authentication_date": "2023-02-07T11:09:15+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "123", "payment_method_type": "card", "authentication_type": "redirect", "authentication_status": "pending", "orderid": "TEST07082023006", "next_step": "redirect", "authentication_error_code": "AUP0000", "authentication_error_type": "pending", "authentication_error_desc": "Authentication Pending", "card": { "masked_value": "xxxxxxxxxxxx1234", "type": "CREDIT", "card_end": "1234", "network": "RUPAY", "issuer": "State Bank of India" } } }, "Rupay OTP flow": { "value": { "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "XUR30656677833", "authentication_date": "2023-03-13T13:47:45+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "UR3", "payment_method_type": "card", "authentication_type": "otp", "authentication_status": "pending", "orderid": "TEST00001200006", "next_step": "capture_otp", "customer_message": "Please enter OTP sent to your mobile", "authentication_error_code": "AUP0000", "authentication_error_type": "pending", "authentication_error_desc": "Authentication Pending", "card": { "masked_value": "xxxxxxxxxxxx6244", "type": "DEBIT", "card_end": "1234", "network": "RUPAY", "issuer": "Punjab National Bank" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Default error": { "value": { "status": 409, "error_type": "duplicate_request_error", "error_code": "AUDRE0001", "message": "Authentication already exist with given mercid and orderid" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "amount": "2.00", "currency": "356", "bankid": "456", "itemcode": "DIRECT", "authentication_type": "3ds2", "3ds_parameter": "merchant", "orderid": "TEST0000009005", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "ru": "https://www.merchanturl.com/response.jsp", "payment_method_type": "card", "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "holder_name": "John Doe" }, "txn_process_type": "y3ds" } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "authentication_type": { "title": "authentication_type", "x-stoplight": { "id": "c33ke2q5rl7ql" }, "type": "string", "description": "Represents the type of authentication initiated in the request, will be fixed value - 3ds2", "enum": [ "3ds2" ], "example": "3ds2" }, "3ds_parameter": { "title": "3ds_parameter", "x-stoplight": { "id": "9cf00xo1tntr9" }, "type": "string", "enum": [ "merchant" ], "description": "Value that determines which entity will capture the device attributes, possible values are merchant" }, "ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "device": { "type": "object", "x-stoplight": { "id": "1dup8vlut7f5l" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" }, "browser_language": { "type": "string", "description": "Value representing the browser language, returned from navigator.language property, for eg. en-US", "maxLength": 5, "example": "en-US", "pattern": "^[A-Za-z\\\\-]{2,5}$" }, "browser_javascript_enabled": { "type": "string", "enum": [ "true", "false" ], "description": "Boolean (true or false) that represents the ability of the cardholder browser to execute JavaScript.\nNote – if true, additional attributes of browser_tz, browser_color_depth, browser_java_enabled, browser_screen_height, browser_screen_width are mandatory" }, "browser_tz": { "type": "string", "description": "Time-zone offset in minutes between UTC and the Cardholder browser local time.\n\nNote that the offset is positive if the local time zone is behind UTC and negative if it is ahead. For eg. if UTC -5 hours then browser_tz = 300 and if UTC +5 hours then browser_tz = -300’", "pattern": "^[0-9\\\\+\\\\-]{2,6}$", "maxLength": 6, "example": "-330" }, "browser_color_depth": { "type": "string", "description": "Value representing the bit depth of the colour palette for displaying images, in bits per pixel.\n\nObtained from Cardholder browser using the screen.Color.Depth property. In case the actual vaue does not exist in the allowed values, use the closest lower value,for eg. 32", "maxLength": 5, "pattern": "^[0-9]{2,5}$", "example": "652" }, "browser_java_enabled": { "type": "string", "description": "Boolean (true or false) that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property", "enum": [ "true", "false" ] }, "browser_screen_height": { "type": "string", "description": "Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property for eg. 601", "pattern": "^[0-9]{2,5}$", "example": "452", "maxLength": 5 }, "browser_screen_width": { "type": "string", "description": "Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property, for eg. 657", "pattern": "^[0-9]{2,5}$", "example": "702", "maxLength": 5 } }, "required": [ "init_channel", "ip", "user_agent", "accept_header", "browser_language", "browser_javascript_enabled" ] }, "card": { "oneOf": [ { "type": "object", "x-stoplight": { "id": "1xxgnveu0ix3k" }, "x-examples": { "Example 1": { "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123", "tokenize": "true", "coft_consent": "true" } } }, "title": "Pay using card number - pan", "properties": { "number": { "type": "string", "example": "4242420000001234", "pattern": "^[0-9]{16}$", "description": "Card number" }, "expiry_month": { "type": "string", "example": "02", "description": "Card expiry month in MM format" }, "expiry_year": { "type": "string", "example": "2029", "description": "Card expiry year in YYYY format" }, "holder_name": { "type": "string", "example": "John Doe", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" }, "cvv": { "type": "string", "example": "123", "description": "Card cvv value" }, "tokenize": { "type": "string", "enum": [ "true" ], "description": "If the card is required to be tokenized then, the value is true" }, "coft_consent": { "type": "string", "enum": [ "true" ], "description": "Fixed value as true, confirming the card holder consent to tokenize the card" } }, "required": [ "number", "expiry_month", "expiry_year", "cvv" ] }, { "type": "object", "x-stoplight": { "id": "ze1cvmk9lawl5" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using network token", "properties": { "network_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "network_token", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "605rgi2ucynyf" }, "x-examples": { "Example 1": { "card": { "issuer_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using issuer token", "properties": { "issuer_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP in the ‘Detokenize’ response", "example": "/1234AAASMuXoH8AmYMoglY1234=", "pattern": "^[a-zA-Z0-9\\\\\\\\/\\\\\\\\!@#\\\\\\\\$%\\\\\\\\^&\\\\\\\\*\\\\\\\\(\\\\\\\\)\\\\\\\\{\\\\\\\\}_\\\\\\\\+\\\\\\\\=\\\\\\\\|:”;’,\\\\\\\\.~`\\\\\\\\-\\\\\\\\\\\\\\\\]{1,256}$" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe" } }, "required": [ "issuer_token", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "dbr5tekgwo4lq" }, "x-examples": { "Example 1": { "card": { "cardaccountid": "CA0AAEF9000000000123", "cvv": "123", "card_end": "0055", "holder_name": "John Doe" } } }, "title": "Pay using card account id", "properties": { "cardaccountid": { "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "example": "CA0AAEF9000000000123" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "holder_name": { "type": "string", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe", "description": "Cardholder name" } }, "required": [ "cardaccountid", "card_end" ] }, { "type": "object", "x-stoplight": { "id": "77jgo8f9g4srj" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using alt id token", "properties": { "altid_token": { "type": "object", "required": [ "altid_value", "altid_cryptogram", "altid_expiry_month", "altid_expiry_year" ], "properties": { "altid_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "altid_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "altid_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "altid_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" }, "altid_trid": { "type": "string", "description": "conditional: required only for AMEX - validate once" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "altid_token", "cvv", "holder_name" ] } ] }, "mandate": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "customer_refid": "CUST614514520010012", "subscription_refid": "SUB614514510012", "subscription_desc": "Unlimited Plan", "start_date": "2023-02-08", "end_date": "2050-12-22", "amount": "774.00", "currency": "356", "frequency": "adho", "amount_type": "max" } }, "properties": { "mercid": { "type": "string", "description": "Unique identifier as defined by BillDesk for each merchant", "example": "BDMERCID", "pattern": "^[A-Za-z0-9]{1,10}$" }, "customer_refid": { "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CUSTREF00A00011" }, "subscription_refid": { "type": "string", "description": "Unique reference assigned by merchant for the subscription", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "SUBREF00A00011" }, "subscription_desc": { "type": "string", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "amount": { "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "200.28" }, "currency": { "type": "string", "description": "ISO currency code for the amount, with a value 356 for INR", "example": "356" }, "frequency": { "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n\n•\tweek - weekly\n•\tmnth - monthly\n•\tbimn – bi-monthly\n•\tqurt - quarterly\n•\tbian – bi-annually\n•\tyear - yearly\n•\tadho – adhoc\n\n", "enum": [ "mnth", "week", "bimn", "qurt", "bian", "year", "adho" ], "example": "adho" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] } }, "required": [ "mercid", "customer_refid", "subscription_refid", "subscription_desc", "start_date", "end_date", "amount", "currency", "frequency", "amount_type" ] }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } }, "required": [ "mercid", "amount", "orderid", "currency", "bankid", "itemcode", "authentication_type", "3ds_parameter", "ru", "payment_method_type", "txn_process_type", "device", "card" ] }, "examples": { "Pay with Card number (Pan)": { "value": { "mercid": "BDMERCID", "amount": "2.00", "currency": "356", "bankid": "456", "itemcode": "DIRECT", "authentication_type": "3ds2", "3ds_parameter": "merchant", "orderid": "TEST0000009005", "ru": "https://www.merchanturl.com/response.jsp", "payment_method_type": "card", "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "holder_name": "John Doe" }, "txn_process_type": "y3ds" } }, "Pay with Network token": { "value": { "mercid": "BDMERCID", "amount": "2.00", "currency": "356", "bankid": "456", "itemcode": "DIRECT", "authentication_type": "3ds2", "3ds_parameter": "merchant", "orderid": "TEST0000009005", "ru": "https://www.merchanturl.com/response.jsp", "payment_method_type": "card", "device": { "device": { "init_channel": "internet", "ip": "123.0.0.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "fingerprintid": "string", "browser_language": "en-US", "browser_javascript_enabled": "true", "browser_tz": "-330", "browser_color_depth": "652", "browser_java_enabled": "true", "browser_screen_height": "452", "browser_screen_width": "702" } }, "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" }, "txn_process_type": "string" } }, "Pay with Issuer token": { "value": { "mercid": "BDMERCID", "amount": "2.00", "currency": "356", "bankid": "456", "itemcode": "DIRECT", "authentication_type": "3ds2", "3ds_parameter": "merchant", "orderid": "TEST0000009005", "ru": "https://www.merchanturl.com/response.jsp", "payment_method_type": "card", "device": { "device": { "init_channel": "internet", "ip": "123.0.0.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "fingerprintid": "string", "browser_language": "en-US", "browser_javascript_enabled": "true", "browser_tz": "-330", "browser_color_depth": "652", "browser_java_enabled": "true", "browser_screen_height": "452", "browser_screen_width": "702" } }, "card": { "issuer_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" }, "txn_process_type": "string" } }, "Pay with Card Account ID": { "value": { "mercid": "BDMERCID", "amount": "2.00", "currency": "356", "bankid": "456", "itemcode": "DIRECT", "authentication_type": "3ds2", "3ds_parameter": "merchant", "orderid": "TEST0000009005", "ru": "https://www.merchanturl.com/response.jsp", "payment_method_type": "card", "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" }, "card": { "cardaccountid": "CA0AAEF9000000000123", "card_end": "0055", "cvv": "123", "holder_name": "John Doe" }, "txn_process_type": "y3ds" } } } } }, "description": "" }, "description": "This endpoint creates a new authentication request to initiate a charge using a payment method.", "tags": [ "Authentication" ] }, "parameters": [] }, "/payments/ve1_2/authentications/validate": { "post": { "summary": "Validate Authentication", "operationId": "validateAuthentication", "responses": { "200": { "description": "OK", "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } }, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "itemcode": "VDDIRECT", "objectid": "authentication", "authenticationid": "A4560000345048", "authentication_date": "2022-03-27T10:33:01+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "456", "payment_method_type": "card", "authentication_type": "redirect", "authentication_status": "success", "orderid": "27000000001", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" }, "enrolled": "Y", "eci": "05", "eci_status": "Y", "cavv": "MjcwMzIyQTQcfrtyMDAzNDUwNDg=", "xid": "MjIwMzIxdtuhjAwMDAzNDUwNDg=", "cavvAlgorithm": "2" } }, "properties": { "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "authenticationid": { "title": "authenticationid", "x-stoplight": { "id": "c1hskskz8e2iq" }, "type": "string", "description": "Unique authenticationid created by BillDesk", "pattern": "^[a-zA-Z0-9]{14,35}$", "example": "A1HM0000389872" }, "authentication_date": { "title": "authentication_date", "x-stoplight": { "id": "uz8duh7gras5w" }, "type": "string", "description": "Authentication date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "authentication_type": { "title": "authentication_type", "x-stoplight": { "id": "c33ke2q5rl7ql" }, "type": "string", "description": "Represents the type of authentication initiated in the request, will be fixed value - 3ds2", "enum": [ "3ds2" ], "example": "3ds2" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "authentication_status": { "title": "authentication_status", "x-stoplight": { "id": "h2j1d7gkgfr54" }, "type": "string", "description": "Represents the status of the request – with possible values as \n•\tpending\n•\tsuccess\n•\tfailure", "enum": [ "pending", "success", "failure" ] }, "authentication_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "authentication_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "authentication_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "eci": { "title": "eci", "x-stoplight": { "id": "jq2g7i098vu5j" }, "type": "string", "description": "Authentication ECI indicator, as per the 3ds protocol (for V, M, D, A cards)" }, "cavv": { "title": "cavv", "x-stoplight": { "id": "72ehfi721p2mm" }, "type": "string", "description": "CAVV value generated by issuer (for V, M, D, A cards)" }, "tranId": { "type": "string" }, "rupay_auth_ref_no": { "title": "rupay_auth_ref_no", "x-stoplight": { "id": "p2pdfeb2zd0g6" }, "type": "string", "description": "Refers to the specific transaction reference provided by NPCI (for R cards)" }, "authenticationValue": { "type": "string" }, "tranCtx_id": { "type": "string" }, "card": { "type": "object", "x-stoplight": { "id": "n1nmwdiqy5hrc" }, "x-examples": { "Example 1": { "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" } } }, "properties": { "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Last 4 digits of the card number \nNote: For an EMI transaction via network token, this attribute value is required for loan booking", "example": "xxxxxxxxxxxx1001" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card network, for eg. visa", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" } } }, "threeds_version": { "title": "threeds_version", "x-stoplight": { "id": "o8scvjfj8moas" }, "type": "string", "description": "Protocol of the 3ds2.0 version used for authentication\n", "enum": [ "2.1.0", "2.2.0" ] }, "ds_transaction_id": { "title": "ds_transaction_id", "x-stoplight": { "id": "wceohqaji2zvf" }, "type": "string", "description": "Directory server transaction id for 3ds2.0", "example": "9ae6259e-08b8-42bb97a2-48d8a1d2a690", "pattern": "^[0-9a-f]{8}[1-5][0-9a-f]{3}[0-9a-f]{12}$" }, "threeds_transaction_id": { "title": "threeds_transaction_id", "x-stoplight": { "id": "c54txyf8e8aqp" }, "type": "string", "description": "Threeds server transaction id", "format": "uuid", "example": "4184a9f8-b0f3-47d2-91ec-bc9939080e32" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } } }, "examples": { "Challenge Flow": { "value": { "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "X4440639244491", "authentication_date": "2023-11-21T14:27:13+05:30", "amount": "499.00", "currency": "356", "mercid": "BDMERCID", "bankid": "444", "payment_method_type": "card", "authentication_type": "3ds2", "authentication_status": "success", "orderid": "TEST07082023006", "eci": "02", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "card": { "masked_value": "xxxxxxxxxxxx1234", "type": "CREDIT", "card_end": "4184", "network": "MASTER", "issuer": "HDFC Bank" }, "cavv": "kBMRIy8dy6AAAAAAAVA82DVhvlpQ", "threeds_version": "2.2.0", "ds_transaction_id": "ef8b6d89-639d-4490-9e38-903691a4087a", "threeds_transaction_id": "36041b77-24db-42f1-87a6-dfbd5797110b" } }, "Rupay Redirection flow": { "value": { "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "X4440639244491", "authentication_date": "2023-02-07T11:09:15+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "444", "payment_method_type": "card", "authentication_type": "redirect", "authentication_status": "success", "orderid": "TEST07082023006", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "card": { "masked_value": "xxxxxxxxxxxx7119", "type": "CREDIT", "card_end": "7119", "network": "RUPAY", "issuer": "State Bank of India" }, "tranId": "100412023020700000000776830623", "rupay_auth_ref_no": "100412023020700000000776830623" } }, "Rupay OTP flow": { "value": { "itemcode": "DIRECT", "objectid": "authentication", "authenticationid": "XUR30656677833", "authentication_date": "2023-03-13T13:47:45+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "UR3", "payment_method_type": "card", "authentication_type": "otp", "authentication_status": "success", "orderid": "TEST00001200006", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "card": { "masked_value": "xxxxxxxxxxxx6244", "type": "DEBIT", "card_end": "6244", "network": "RUPAY", "issuer": "Punjab National Bank" }, "tranCtx_id": "100122023031300000000799960114", "authenticationValue": "c853917f9b07017ee3beb0672fbdffb66868cb2e5a436376ab5e7f35c48e64dd2.00&AAABAHaWFSNjIVQiJpYVAAACMHI=", "rupay_auth_ref_no": "100412023020700000000776830623" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal Server Error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Default error": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "AUAVE0004", "message": "Authentication already validated" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "authenticationid": "A4560000345048", "payment_method_type": "card", "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "holder_name": "John Doe" }, "response_parameters": { "cres": "eJytmFmvo8iSgN/5Fa26j1Y3qxdariMlO9hgsy8vIwyYfTGLWX794HP6VFXX1Ghujy7S0UmCzMiIzIgv0nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl88vF+ivl/jvm6mfrze/W+TZS3g" } } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "authenticationid": { "title": "authenticationid", "x-stoplight": { "id": "c1hskskz8e2iq" }, "type": "string", "description": "Unique authenticationid created by BillDesk", "pattern": "^[a-zA-Z0-9]{14,35}$", "example": "A1HM0000389872" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "response_parameters": { "type": "object", "x-examples": { "Example 1": { "cres": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g", "AccuResponseCode": "ACCU000", "session": "X4440639244491", "AccuGuid": "a13df076-5c82-4fbf-aa5c-be11e9847e9a", "AccuRequestId": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==", "MD": "", "Pares": "" } }, "properties": { "cres": { "type": "string", "description": "Response parameters as received from the issuer, and will be cres for 3ds 2.0 flow", "example": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g" }, "AccuResponseCode": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "ACCU000 " }, "session": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "X4440639244491" }, "AccuGuid": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "a13df076-5c82-4fbf-aa5c-be11e9847e9a" }, "AccuRequestId": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==\"" }, "otp": { "type": "string", "description": "for a native authentication where next_step = capture_otp" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } } }, "required": [ "mercid", "authenticationid", "payment_method_type", "response_parameters" ] }, "examples": { "Challenge Flow": { "value": { "authenticationid": "A4560000345048", "payment_method_type": "card", "response_parameters": { "cres": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g" } } }, "Rupay Redirect flow": { "value": { "authenticationid": "X4440639244491", "response_parameters": { "AccuResponseCode": "ACCU000", "session": "X4440639244491", "AccuGuid": "a13df076-5c82-4fbf-aa5c-be11e9847e9a", "AccuRequestId": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==" } } }, "Rupay OTP Flow": { "value": { "authenticationid": "XUR30656677833", "response_parameters": { "otp": "123456" } } } } } }, "description": "" }, "tags": [ "Authentication" ], "description": "" } }, "/payments/ve1_2/authentications/get": { "post": { "summary": "Retrieve Authentication", "operationId": "retrieveAuthentication", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "itemcode": "VDDIRECT", "objectid": "authentication", "authenticationid": "A4560000345048", "authentication_date": "2022-03-27T10:33:01+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "456", "payment_method_type": "card", "authentication_type": "redirect", "authentication_status": "success", "orderid": "27000000001", "enrolled": "Y", "eci": "05", "eci_status": "Y", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" }, "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" }, "cavv": "MjcwMzIyQTQcfrtyMDAzNDUwNDg=", "xid": "MjIwMzIxdtuhjAwMDAzNDUwNDg=", "cavvAlgorithm": "2" } }, "properties": { "itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "authenticationid": { "title": "authenticationid", "x-stoplight": { "id": "c1hskskz8e2iq" }, "type": "string", "description": "Unique authenticationid created by BillDesk", "pattern": "^[a-zA-Z0-9]{14,35}$", "example": "A1HM0000389872" }, "authentication_date": { "title": "authentication_date", "x-stoplight": { "id": "uz8duh7gras5w" }, "type": "string", "description": "Authentication date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "authentication_type": { "title": "authentication_type", "x-stoplight": { "id": "c33ke2q5rl7ql" }, "type": "string", "description": "Represents the type of authentication initiated in the request, will be fixed value - 3ds2", "enum": [ "3ds2" ], "example": "3ds2" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "authentication_status": { "title": "authentication_status", "x-stoplight": { "id": "h2j1d7gkgfr54" }, "type": "string", "description": "Represents the status of the request – with possible values as \n•\tpending\n•\tsuccess\n•\tfailure", "enum": [ "pending", "success", "failure" ] }, "authentication_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "authentication_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "authentication_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "card": { "type": "object", "x-stoplight": { "id": "n1nmwdiqy5hrc" }, "x-examples": { "Example 1": { "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" } } }, "properties": { "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Last 4 digits of the card number \nNote: For an EMI transaction via network token, this attribute value is required for loan booking", "example": "xxxxxxxxxxxx1001" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card network, for eg. visa", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" } } }, "eci": { "title": "eci", "x-stoplight": { "id": "jq2g7i098vu5j" }, "type": "string", "description": "Authentication ECI indicator, as per the 3ds protocol (for V, M, D, A cards)" }, "cavv": { "title": "cavv", "x-stoplight": { "id": "72ehfi721p2mm" }, "type": "string", "description": "CAVV value generated by issuer (for V, M, D, A cards)" }, "rupay_auth_ref_no": { "title": "rupay_auth_ref_no", "x-stoplight": { "id": "p2pdfeb2zd0g6" }, "type": "string", "description": "Refers to the specific transaction reference provided by NPCI (for R cards)" }, "threeds_version": { "title": "threeds_version", "x-stoplight": { "id": "o8scvjfj8moas" }, "type": "string", "description": "Protocol of the 3ds2.0 version used for authentication\n", "enum": [ "2.1.0", "2.2.0" ] }, "ds_transaction_id": { "title": "ds_transaction_id", "x-stoplight": { "id": "wceohqaji2zvf" }, "type": "string", "description": "Directory server transaction id for 3ds2.0", "example": "9ae6259e-08b8-42bb97a2-48d8a1d2a690", "pattern": "^[0-9a-f]{8}[1-5][0-9a-f]{3}[0-9a-f]{12}$" }, "threeds_transaction_id": { "title": "threeds_transaction_id", "x-stoplight": { "id": "c54txyf8e8aqp" }, "type": "string", "description": "Threeds server transaction id", "format": "uuid", "example": "4184a9f8-b0f3-47d2-91ec-bc9939080e32" }, "additional_info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } } }, "required": [ "mercid" ] }, "examples": { "Response": { "value": { "itemcode": "VDDIRECT", "objectid": "authentication", "authenticationid": "A4560000345048", "authentication_date": "2022-03-27T10:33:01+05:30", "amount": "2.00", "currency": "356", "mercid": "BDMERCID", "bankid": "456", "payment_method_type": "card", "authentication_type": "redirect", "authentication_status": "success", "orderid": "27000000001", "enrolled": "Y", "eci": "05", "eci_status": "Y", "authentication_error_code": "AUS0000", "authentication_error_type": "success", "authentication_error_desc": "Authentication Successful", "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" }, "cavv": "kBMRIy8dy6JAAAAAADVhvlpQ", "threeds_version": "2.2.0", "ds_transaction_id": "ef8b6d89-639d-4490-9e38-903691a4087a", "threeds_transaction_id": "36041b77-24db-42f1-87a6-dfbd5797110b" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Forbidden": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Internal server error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } }, "default": { "description": "Any bad or invalid request will lead to following error object", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "examples": { "Authentication id not found": { "value": { "status": 422, "error_type": "invalid_data_error", "error_code": "AUIDE0018", "message": "Invalid authenticationid" } } } } }, "headers": { "BD-Traceid": { "schema": { "type": "string" }, "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail." }, "Content-Type": { "schema": { "type": "string" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "schema": { "type": "string" }, "description": "Accept Response Content-Type to take the values application/jose" } } } }, "parameters": [ { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "authenticationid": "A4560000345048" } }, "properties": { "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "authenticationid": { "title": "authenticationid", "x-stoplight": { "id": "c1hskskz8e2iq" }, "type": "string", "description": "Unique authenticationid created by BillDesk", "pattern": "^[a-zA-Z0-9]{14,35}$", "example": "A1HM0000389872" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" } }, "required": [ "mercid" ] }, "examples": { "Using authenticationid": { "value": { "mercid": "BDMERCID", "authenticationid": "A4560000345048" } }, "Using orderid": { "value": { "mercid": "BDMERCID", "orderid": "27000000001" } } } } } }, "tags": [ "Authentication" ], "description": "This endpoint retrieves the details of a particular authentication using either of `mercid` and `orderid` or `transactionid`." } } }, "components": { "parameters": { "bdTraceId": { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, "bdTimeStamp": { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, "Content-Type": { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, "Accept": { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" }, "Recurring_Accept": { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" }, "Recurring_Content-Type": { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, "Recurring_BdTimeStamp": { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, "Recurring_BdTraceId": { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, "Openapi_Accept": { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/jose" }, "description": "Accept Response Content-Type to take the values application/jose" }, "Openapi_Content-Type": { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" }, "description": "Request Content-Type to take the values application/jose" }, "Openapi_BdTimeStamp": { "in": "header", "name": "BD-Timestamp", "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.", "required": true, "schema": { "type": "string", "example": "20201203182838" } }, "Openapi_BdTraceId": { "in": "header", "name": "BD-Traceid", "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.", "required": true, "schema": { "type": "string", "example": "20201203182838" } } }, "examples": { "links": { "summary": "Summary of the link", "description": "Description of the link", "value": [ { "href": "https://www.billdesk.com/pgi/ve2_5/orders/ord012345678", "rel": "self", "method": "GET" }, { "href": "https://www.billdesk.com/pgi/paymentoptions/a34df916c7ae42678", "rel": "redirect", "method": "POST", "parameters": { "mercid": "BDMERCID", "bdorderid": "ord012345678" }, "valid_date": "2018-02-22T11:32:23+05:30" } ] }, "403-error": { "value": { "status": 403, "error_type": "inaccessable_resource_error", "error_code": "GNIAE0002", "message": "Access forbidden" } }, "500-error": { "value": { "status": 500, "error_type": "api_processing_error", "error_code": "AUAPE0001", "message": "Internal server error" } }, "Default-error": { "value": { "status": 409, "error_type": "duplicate_request_error", "error_code": "AUDRE0001", "message": "Authentication already exist with given mercid and orderid" } }, "422-error": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "AUAVE0004", "message": "Authentication already validated" } }, "422-auth-id-not-found-error": { "value": { "status": 422, "error_type": "invalid_data_error", "error_code": "AUIDE0018", "message": "Invalid authenticationid" } }, "422-Invalid-merchant-config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } }, "requestBodies": {}, "schemas": { "mandate_tokenid": { "title": "mandate_tokenid", "x-stoplight": { "id": "169b004872de3" }, "type": "string", "description": "Unique value generated by BillDesk for each mandate_token created by the merchant" }, "bdorderid": { "title": "bdorderid", "x-stoplight": { "id": "m13q2fo7bn801" }, "type": "string", "description": "Unique value generated by BillDesk for each order id generated using Create Order API" }, "rdata": { "title": "rdata", "x-stoplight": { "id": "lftrd03d82vvp" }, "type": "string", "description": "Unique key generated by BillDesk for each request", "x-examples": {} }, "authorization": { "title": "authorization", "x-stoplight": { "id": "7j04iqr3yp3z3" }, "type": "string", "description": "Unique value generated by BillDesk for each request" }, "3ds_parameter": { "title": "3ds_parameter", "x-stoplight": { "id": "9cf00xo1tntr9" }, "type": "string", "enum": [ "merchant" ], "description": "Value that determines which entity will capture the device attributes, possible values are merchant" }, "Additional-Info": { "type": "object", "x-examples": { "Example 1": { "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2", "additional_info3": "Details3", "additional_info4": "Details4", "additional_info5": "Details5", "additional_info6": "Details6", "additional_info7": "Details7", "additional_info8": "Details8", "additional_info9": "Details9", "additional_info10": "Details10" } } }, "description": "Array of 7 additional_info values that can be attached to\nthe transaction.\nNote: Merchant is advised to not pass customer PII\ninformation in additional info fields.", "properties": { "additional_info1": { "type": "string", "example": "Details1" }, "additional_info2": { "type": "string", "example": "Details2" }, "additional_info3": { "type": "string", "example": "Details3" }, "additional_info4": { "type": "string", "example": "Details4" }, "additional_info5": { "type": "string", "example": "Details5" }, "additional_info6": { "type": "string", "example": "Details6" }, "additional_info7": { "type": "string", "example": "Details7" } } }, "Card-Response": { "type": "object", "x-stoplight": { "id": "n1nmwdiqy5hrc" }, "x-examples": { "Example 1": { "card": { "type": "DEBIT", "card_end": "1234", "network": "VISA", "issuer": "ABC Bank" } } }, "properties": { "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Last 4 digits of the card number \nNote: For an EMI transaction via network token, this attribute value is required for loan booking", "example": "xxxxxxxxxxxx1001" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card network, for eg. visa", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" } } }, "Device": { "type": "object", "x-stoplight": { "id": "1dup8vlut7f5l" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" }, "browser_language": { "type": "string", "description": "Value representing the browser language, returned from navigator.language property, for eg. en-US", "maxLength": 5, "example": "en-US", "pattern": "^[A-Za-z\\\\-]{2,5}$" }, "browser_javascript_enabled": { "type": "string", "enum": [ "true", "false" ], "description": "Boolean (true or false) that represents the ability of the cardholder browser to execute JavaScript.\nNote – if true, additional attributes of browser_tz, browser_color_depth, browser_java_enabled, browser_screen_height, browser_screen_width are mandatory" }, "browser_tz": { "type": "string", "description": "Time-zone offset in minutes between UTC and the Cardholder browser local time.\n\nNote that the offset is positive if the local time zone is behind UTC and negative if it is ahead. For eg. if UTC -5 hours then browser_tz = 300 and if UTC +5 hours then browser_tz = -300’", "pattern": "^[0-9\\\\+\\\\-]{2,6}$", "maxLength": 6, "example": "-330" }, "browser_color_depth": { "type": "string", "description": "Value representing the bit depth of the colour palette for displaying images, in bits per pixel.\n\nObtained from Cardholder browser using the screen.Color.Depth property. In case the actual vaue does not exist in the allowed values, use the closest lower value,for eg. 32", "maxLength": 5, "pattern": "^[0-9]{2,5}$", "example": "652" }, "browser_java_enabled": { "type": "string", "description": "Boolean (true or false) that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property", "enum": [ "true", "false" ] }, "browser_screen_height": { "type": "string", "description": "Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property for eg. 601", "pattern": "^[0-9]{2,5}$", "example": "452", "maxLength": 5 }, "browser_screen_width": { "type": "string", "description": "Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property, for eg. 657", "pattern": "^[0-9]{2,5}$", "example": "702", "maxLength": 5 } }, "required": [ "init_channel", "ip", "user_agent", "accept_header", "browser_language", "browser_javascript_enabled" ] }, "Error-object": { "type": "object", "properties": { "status": { "type": "integer", "description": "This will be same as HTTP response code" }, "error_type": { "type": "string", "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc." }, "error_code": { "type": "string", "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction" }, "message": { "type": "string", "description": "More details as a description for the error_code" } } }, "IFSC": { "title": "IFSC", "x-stoplight": { "id": "grn65kr3i0pk0" }, "type": "string", "description": "IFSC of the bank account number", "pattern": "^[A-Za-z]{4}[a-zA-Z0-9]{7}$", "example": "IDBK10000002" }, "Mandate-Response": { "type": "object", "properties": { "objectid": { "type": "string" }, "mercid": { "type": "string" }, "customer_refid": { "type": "string" }, "subscription_refid": { "type": "string" }, "subscription_desc": { "type": "string" }, "amount": { "type": "string" }, "amount_type": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "frequency": { "type": "string" }, "payment_method_type": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "mandateid": { "type": "string" }, "createdon": { "type": "string" }, "verification_error_code": { "type": "string" }, "verification_error_type": { "type": "string" }, "verification_error_desc": { "type": "string" } }, "x-examples": { "Example 1": { "objectid": "mandate", "mercid": "BDMERCID", "customer_refid": "CUSTREF00A00011", "subscription_refid": "SUBREF00A00011", "subscription_desc": "Family Plan", "amount": "1500.00", "amount_type": "maximum", "start_date": "2021-05-16", "end_date": "2029-10-22", "frequency": "adho", "payment_method_type": "card", "currency": "356", "status": "pending", "mandateid": "MA0DDD00050243", "createdon": "2021-05-16T18:23:11+05:30", "verification_error_code": "TRS0000", "verification_error_type": "success", "verification_error_desc": "Transaction Successful" } } }, "Mandate": { "type": "object", "x-examples": { "Example 1": { "mercid": "BDMERCID", "customer_refid": "CUST614514520010012", "subscription_refid": "SUB614514510012", "subscription_desc": "Unlimited Plan", "start_date": "2023-02-08", "end_date": "2050-12-22", "amount": "774.00", "currency": "356", "frequency": "adho", "amount_type": "max" } }, "properties": { "mercid": { "type": "string", "description": "Unique identifier as defined by BillDesk for each merchant", "example": "BDMERCID", "pattern": "^[A-Za-z0-9]{1,10}$" }, "customer_refid": { "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CUSTREF00A00011" }, "subscription_refid": { "type": "string", "description": "Unique reference assigned by merchant for the subscription", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "SUBREF00A00011" }, "subscription_desc": { "type": "string", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "end_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "amount": { "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "200.28" }, "currency": { "type": "string", "description": "ISO currency code for the amount, with a value 356 for INR", "example": "356" }, "frequency": { "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n\n•\tweek - weekly\n•\tmnth - monthly\n•\tbimn – bi-monthly\n•\tqurt - quarterly\n•\tbian – bi-annually\n•\tyear - yearly\n•\tadho – adhoc\n\n", "enum": [ "mnth", "week", "bimn", "qurt", "bian", "year", "adho" ], "example": "adho" }, "amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] } }, "required": [ "mercid", "customer_refid", "subscription_refid", "subscription_desc", "start_date", "end_date", "amount", "currency", "frequency", "amount_type" ] }, "Pay-using-altid": { "type": "object", "x-stoplight": { "id": "77jgo8f9g4srj" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using alt id token", "properties": { "altid_token": { "type": "object", "required": [ "altid_value", "altid_cryptogram", "altid_expiry_month", "altid_expiry_year" ], "properties": { "altid_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "altid_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "altid_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "altid_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" }, "altid_trid": { "type": "string", "description": "conditional: required only for AMEX - validate once" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "altid_token", "cvv", "holder_name" ] }, "Pay-using-card-account-id": { "type": "object", "x-stoplight": { "id": "dbr5tekgwo4lq" }, "x-examples": { "Example 1": { "card": { "cardaccountid": "CA0AAEF9000000000123", "cvv": "123", "card_end": "0055", "holder_name": "John Doe" } } }, "title": "Pay using card account id", "properties": { "cardaccountid": { "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "example": "CA0AAEF9000000000123" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "holder_name": { "type": "string", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe", "description": "Cardholder name" } }, "required": [ "cardaccountid", "card_end" ] }, "Pay-using-card-number-pan": { "type": "object", "x-stoplight": { "id": "1xxgnveu0ix3k" }, "x-examples": { "Example 1": { "card": { "number": "4242420000001234", "expiry_month": "12", "expiry_year": "2029", "holder_name": "John Doe", "cvv": "123", "tokenize": "true", "coft_consent": "true" } } }, "title": "Pay using card number - pan", "properties": { "number": { "type": "string", "example": "4242420000001234", "pattern": "^[0-9]{16}$", "description": "Card number" }, "expiry_month": { "type": "string", "example": "02", "description": "Card expiry month in MM format" }, "expiry_year": { "type": "string", "example": "2029", "description": "Card expiry year in YYYY format" }, "holder_name": { "type": "string", "example": "John Doe", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" }, "cvv": { "type": "string", "example": "123", "description": "Card cvv value" }, "tokenize": { "type": "string", "enum": [ "true" ], "description": "If the card is required to be tokenized then, the value is true" }, "coft_consent": { "type": "string", "enum": [ "true" ], "description": "Fixed value as true, confirming the card holder consent to tokenize the card" } }, "required": [ "number", "expiry_month", "expiry_year", "cvv" ] }, "Pay-using-issuer-token": { "type": "object", "x-stoplight": { "id": "605rgi2ucynyf" }, "x-examples": { "Example 1": { "card": { "issuer_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using issuer token", "properties": { "issuer_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP in the ‘Detokenize’ response", "example": "/1234AAASMuXoH8AmYMoglY1234=", "pattern": "^[a-zA-Z0-9\\\\\\\\/\\\\\\\\!@#\\\\\\\\$%\\\\\\\\^&\\\\\\\\*\\\\\\\\(\\\\\\\\)\\\\\\\\{\\\\\\\\}_\\\\\\\\+\\\\\\\\=\\\\\\\\|:”;’,\\\\\\\\.~`\\\\\\\\-\\\\\\\\\\\\\\\\]{1,256}$" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value ", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$", "example": "John Doe" } }, "required": [ "issuer_token", "card_end" ] }, "Pay-using-network-token": { "type": "object", "x-stoplight": { "id": "ze1cvmk9lawl5" }, "x-examples": { "Example 1": { "card": { "network_token": { "token_value": "1234383920541234", "token_cryptogram": "/1234AAASMuXoH8AmYMoglY1234=", "token_expiry_month": "12", "token_expiry_year": "2029" }, "card_end": "0004", "cvv": "123", "holder_name": "John Doe" } } }, "title": "Pay using network token", "properties": { "network_token": { "type": "object", "required": [ "token_value", "token_cryptogram", "token_expiry_month", "token_expiry_year" ], "properties": { "token_value": { "type": "string", "description": "Token Value – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "1234383920541234" }, "token_cryptogram": { "type": "string", "description": "Token Cryptogram – as received from TSP, provided in the ‘Detokenize’ response", "pattern": "^[a-zA-Z0-9\\\\/\\\\!@#\\\\$%\\\\^&\\\\*\\\\(\\\\)\\\\{\\\\}_\\\\+\\\\=\\\\|:”;’,\\\\.~`\\\\-\\\\\\\\]{1,256}$", "example": "/1234AAASMuXoH8AmYMoglY1234=" }, "token_expiry_month": { "type": "integer", "example": "02", "description": "Token Expiry Month – as received from TSP in the MM format" }, "token_expiry_year": { "type": "integer", "example": 2029, "description": "Token Expiry Year – as received from TSP in the YYYY format" } } }, "card_end": { "type": "string", "description": "Last 4 digits of the card number \n\nNote: For an EMI transaction via network token,this attribute value is required for loan booking", "example": "0045" }, "cvv": { "type": "string", "description": "Card cvv value", "example": "123" }, "holder_name": { "type": "string", "description": "Cardholder name", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\\\\\s\\\\\\\\.'\\\\\\\\-\\\\\\\\~\\\\\\\\@\\\\\\\\_]{1,120}$" } }, "required": [ "network_token", "card_end" ] }, "Response-parameters": { "type": "object", "x-examples": { "Example 1": { "cres": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g", "AccuResponseCode": "ACCU000", "session": "X4440639244491", "AccuGuid": "a13df076-5c82-4fbf-aa5c-be11e9847e9a", "AccuRequestId": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==", "MD": "", "Pares": "" } }, "properties": { "cres": { "type": "string", "description": "Response parameters as received from the issuer, and will be cres for 3ds 2.0 flow", "example": "eJytmFmvo8iSgN/5Fa26j 1Y3qxdariMlO9hgsy8vIwyYfTGLWX7 94HP6VFXX1Ghujy7S0UmCzMiIzIgv0 nk0kjaKGD0KhjZ6O8pR1XyXA364Xvl 88vF+ivl/jvm6mfrze/W+TZS3g" }, "AccuResponseCode": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "ACCU000 " }, "session": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "X4440639244491" }, "AccuGuid": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "a13df076-5c82-4fbf-aa5c-be11e9847e9a" }, "AccuRequestId": { "type": "string", "description": "Response parameters as received from the issuer, and will be received for Rupay cards", "example": "MGI2ZTE2M2RjYzJjNTBhMDlkMzA1OTc2NmU3OTBjOTdjNjk3NjA5MDdmY2RlMDI1MTA1MDBjOTYyMzMyODNjNg==\"" }, "otp": { "type": "string", "description": "for a native authentication where next_step = capture_otp" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } }, "Amount": { "title": "amount", "x-stoplight": { "id": "s5xd8bwxp2orm" }, "type": "string", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28", "description": "Transaction amount in two decimals, eg. 299.28" }, "Amount_type": { "title": "amount_type", "x-stoplight": { "id": "o7dqaslkupvxa" }, "type": "string", "description": "Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible\n•\tmaximum - indicates the maximum amount that can be charged for the subscription\n•\tfixed – indicates the fixed amount to be charged for the subscription\nPlease note: For upi, only \"maximum\" is allowed. This is required to allow for token debit (small value transaction)\n", "enum": [ "maximum", "fixed" ] }, "Auth_status": { "title": "auth_status", "x-stoplight": { "id": "35i21snltcrdq" }, "type": "string", "description": "Represents the authorization status of the transaction with the following possible values:\n•\t0300 - transaction is successful\n•\t0002 - transaction is pending for authorization\n•\t0399 - transaction failed", "enum": [ "0300", "0002", "0399" ] }, "Authcode": { "title": "authcode", "x-stoplight": { "id": "a760wo51p1b9k" }, "type": "string", "description": "Authorization code received from the acquirer for a successfully authorized card transaction" }, "Authentication_date": { "title": "authentication_date", "x-stoplight": { "id": "uz8duh7gras5w" }, "type": "string", "description": "Authentication date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "Authentication_status": { "title": "authentication_status", "x-stoplight": { "id": "h2j1d7gkgfr54" }, "type": "string", "description": "Represents the status of the request – with possible values as \n•\tpending\n•\tsuccess\n•\tfailure", "enum": [ "pending", "success", "failure" ] }, "Authentication_type": { "title": "authentication_type", "x-stoplight": { "id": "c33ke2q5rl7ql" }, "type": "string", "description": "Represents the type of authentication initiated in the request, will be fixed value - 3ds2", "enum": [ "3ds2" ], "example": "3ds2" }, "Authenticationid": { "title": "authenticationid", "x-stoplight": { "id": "c1hskskz8e2iq" }, "type": "string", "description": "Unique authenticationid created by BillDesk", "pattern": "^[a-zA-Z0-9]{14,35}$", "example": "A1HM0000389872" }, "Avs-request": { "type": "object", "x-examples": { "Example 1": { "bankaccount": [ { "number": "12233445566", "ifsc": "IDBK10000002", "name": "John Doe" }, { "number": "12233445567", "ifsc": "IDBK10000002", "name": "John Doe" } ] } }, "description": "This API can be used to verify the bank account number by initiating a penny drop to the account. For upi, validation is done at acquiring bank end ", "title": "Account validation", "properties": { "bankaccounts": { "type": "array", "items": { "type": "object", "properties": { "number": { "description": "Customer's bank account number", "title": "bankacc_number", "x-stoplight": { "id": "9nwo0pwlz0qos" }, "type": "string", "pattern": "^\\\\d{9,18}$", "example": "12233445566" }, "ifsc": { "description": "IFSC of the bank account number", "title": "IFSC", "x-stoplight": { "id": "grn65kr3i0pk0" }, "type": "string", "pattern": "^[A-Za-z]{4}[a-zA-Z0-9]{7}$", "example": "IDBK10000002" }, "name": { "description": "Name of the bank account holder", "title": "bankaccount_holder_name", "x-stoplight": { "id": "jedjceugzit8g" }, "type": "string", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$" } }, "required": [ "number", "ifsc" ] } } } }, "Avs-response": { "type": "object", "x-examples": { "Example 1": { "bankaccount": [ { "number": "xxxxxxxxx5566", "ifsc": "IDBK10000002", "name": "John Doe" }, { "number": "xxxxxxxxx5567", "ifsc": "IDBK10000002", "name": "John Doe" } ], "account_matched": "true", "name_matched": "true" } }, "properties": { "bankaccount": { "type": "array", "description": "Details of the bank account", "items": { "type": "object", "properties": { "number": { "title": "bankacc_number", "x-stoplight": { "id": "9nwo0pwlz0qos" }, "type": "string", "description": "Bank account number", "pattern": "^\\\\d{9,18}$", "example": "12233445566" }, "ifsc": { "title": "IFSC", "x-stoplight": { "id": "grn65kr3i0pk0" }, "type": "string", "description": "IFSC of the bank account number", "pattern": "^[A-Za-z]{4}[a-zA-Z0-9]{7}$", "example": "IDBK10000002" }, "name": { "title": "bankaccount_holder_name", "x-stoplight": { "id": "jedjceugzit8g" }, "type": "string", "description": "Name of the bank account holder", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$" } } } }, "account_matched": { "type": "string", "description": "Boolean value (true or false) that indicates the status of account matching", "enum": [ "true", "false" ] }, "name_matched": { "type": "string", "description": "Boolean value (true or false) that indicates the status of name matching", "enum": [ "true", "false" ] } }, "description": "" }, "Bank_ref_no": { "title": "bank_ref_no", "x-stoplight": { "id": "tls0w5ung6eha" }, "type": "string", "description": "Transaction reference number generated by bank or acquirer " }, "Bankacc_number": { "title": "bankacc_number", "x-stoplight": { "id": "9nwo0pwlz0qos" }, "type": "string", "description": "Bank account number", "pattern": "^\\\\d{9,18}$", "example": "12233445566" }, "Bankaccount_holder_name": { "title": "bankaccount_holder_name", "x-stoplight": { "id": "jedjceugzit8g" }, "type": "string", "description": "Name of the bank account holder", "example": "John Doe", "pattern": "^[A-Za-z0-9\\\\s\\\\.'\\\\-\\\\~\\\\@\\\\_]{1,120}$" }, "Bankid": { "title": "bankid", "x-stoplight": { "id": "gf7ntync4cj73" }, "type": "string", "description": "BillDesk defined unique identifier for acquirer\nMandatory for Upi and Netbanking flows", "example": "1HM", "pattern": "^[A-Za-z0-9]{1,10}$" }, "Card_issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" }, "Card_network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card Network", "example": "VISA, MASTER" }, "Card_type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "Cardaccount-in-txn-response": { "type": "object", "x-examples": { "Example 1": { "masked_value": "xxxxxxxxxxxx8556", "type": "CREDIT", "card_end": "8556", "network": "VISA", "issuer": "HDFC Bank", "cardaccountid": "CA03E63F000027391234", "coft_consent": "true", "cardaccount": { "objectid": "cardaccount", "mercid": "BDMERCID", "customer_refid": "TST1305202312260002", "cardaccountid": "CA026D01000027391234", "orderid": "TXN1305202312260002", "masked_value": "xxxxxxxxxxxx8556", "holder_name": "NA", "issuer": "HDFC BANK", "network": "VISA", "status": "ACTIVE", "coft_consent": "true", "createdon": "2023-05-13T12:28:41+05:30", "network_token": { "token_ref_no": "55933247caa42c4842c012bb81641234", "token_expiry_month": "12", "token_expiry_year": "2025", "status": "ACTIVE", "createdon": "2023-05-13T12:28:41+05:30" } } } }, "properties": { "masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Masked card number, with the last four digits", "example": "xxxxxxxxxxxx1001" }, "type": { "title": "card_type", "x-stoplight": { "id": "r4tyk0ee6k6u5" }, "type": "string", "description": "Card product type, takes the following values - debit, credit or prepaid", "example": "debit, credit, prepaid" }, "card_end": { "type": "string" }, "network": { "title": "card_network", "x-stoplight": { "id": "fmhnjhdrk4ngb" }, "type": "string", "description": "Card Network", "example": "VISA, MASTER" }, "issuer": { "title": "card_issuer", "x-stoplight": { "id": "tm5adiwnqv7q0" }, "type": "string", "description": "Card issuer" }, "cardaccountid": { "title": "cardaccountid", "x-stoplight": { "id": "12f6yszzh3x5y" }, "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "CA0AAEF9000000000123" }, "coft_consent": { "type": "string" }, "cardaccount": { "type": "object", "properties": { "objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "cardaccountid": { "type": "string" }, "orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "masked_value": { "type": "string" }, "holder_name": { "title": "holder_name", "x-stoplight": { "id": "azsrpizyvmymk" }, "type": "string", "description": "Cardholder name" }, "cardaccount_status": { "type": "string" }, "createdon": { "type": "string" }, "network_token": { "type": "object", "properties": { "token_ref_no": { "type": "string" }, "token_expiry_month": { "type": "string" }, "token_expiry_year": { "type": "string" }, "status": { "type": "string" }, "createdon": { "type": "string" } } }, "cardaccount_error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "cardaccount_error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "cardaccount_error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" } } } }, "title": "" }, "Cardaccountid": { "title": "cardaccountid", "x-stoplight": { "id": "12f6yszzh3x5y" }, "type": "string", "description": "Unique ID created by BillDesk for the combination of card number, mercid and customer_refid", "pattern": "^[A-Za-z0-9]{1,35}$", "example": "CA0AAEF9000000000123" }, "Cavv": { "title": "cavv", "x-stoplight": { "id": "72ehfi721p2mm" }, "type": "string", "description": "CAVV value generated by issuer (for V, M, D, A cards)" }, "Charge_amount": { "title": "charge_amount", "x-stoplight": { "id": "m2z4sf48a8a5w" }, "type": "string", "description": "Total charge to the customer" }, "Createdon": { "title": "createdon", "x-stoplight": { "id": "k3ewegvbimz0g" }, "type": "string", "description": "object creation timestamp", "format": "date-time" }, "Currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "Customer": { "title": "customer", "x-examples": { "Example 1": { "first_name": "John", "last_name": "Doe", "mobile": "9800000000", "mobile_alt": "9800000000", "email": "john.doe@somedomain.com", "email_alt": "john.doe@somedomain.com" } }, "type": "object", "properties": { "first_name": { "type": "string", "description": "Customer’s First Name", "example": "John" }, "last_name": { "type": "string", "description": "Customer’s Last Name", "example": "Doe" }, "mobile": { "type": "string", "description": "Customer’s Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979988" }, "mobile_alt": { "type": "string", "description": "Customer’s Alternate Mobile number", "pattern": "^[\\\\+]{0,1}[0-9]{5,15}$", "example": "9022979982" }, "email": { "type": "string", "description": "Customer’s Email address", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$", "example": "abc@xyz.com" }, "email_alt": { "type": "string", "description": "Customer’s alternate Email Address", "example": "abc@xyz.com", "pattern": "^[_A-Za-z0-9-\\\\+]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\\\.[A-Za-z0-9\\\\-]+)*(\\\\.[A-Za-z]{2,6})$" } }, "required": [ "first_name", "last_name" ] }, "Customer_refid": { "title": "customer_refid", "x-stoplight": { "id": "mpmq18zbl4x12" }, "type": "string", "description": "Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer\nRequired for mandate and tokenization", "pattern": "^[A-Za-z0-9\\\\_\\\\:\\\\-]{1,80}$", "example": "CSREF00001" }, "Debit_day": { "title": "debit_day", "x-stoplight": { "id": "ppp2ede7qx3fc" }, "type": "string", "description": "Required only where payment_method_type = upi. Default value \"1\" to be passed\n", "pattern": "^\\\\d{1,2}$", "example": "1", "enum": [ "1" ] }, "Device-order": { "type": "object", "x-stoplight": { "id": "bu2ij616i2uce" }, "x-examples": { "Example 1": { "device": { "init_channel": "internet", "ip": "124.124.1.1", "mac": "11-AC-58-21-1B-AA", "imei": "990000112233445", "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv:51.0)Gecko/20100101Firefox/51.0", "accept_header": "text/html", "fingerprintid": "61b12c18b5d0cf901be34a23ca64bb19", "browser_tz": "-330", "browser_color_depth": "32", "browser_java_enabled": "false", "browser_screen_height": "601", "browser_screen_width": "657", "browser_language": "en-US", "browser_javascript_enabled": "true" } } }, "title": "Device", "description": "Device", "properties": { "init_channel": { "type": "string", "description": "Initiating channel,accepted values are internet,app or kiosk", "enum": [ "internet", "app", "kiosk" ] }, "ip": { "type": "string", "description": "Actual end customer IP address is required to be passed", "maxLength": 15 }, "user_agent": { "type": "string", "description": "Exact content of the HTTP user-agent header\n\nNote: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion", "example": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0", "pattern": "=^[A-Za-z0-9\\\\_\\\\:\\\\-\\\\,\\\\;\\\\/\\\\)\\\\(\\\\.\\\\s\\\\+\\\\[\\\\]\\\\=@]{10,255}$" }, "accept_header": { "type": "string", "description": "Customer browser accept header values", "maxLength": 255, "example": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "pattern": "^[0-9A-Za-z\\\\.\\\\+\\\\-\\\\/\\\\=\\\\*\\\\,\\\\;]{10,255}$" } }, "required": [ "init_channel", "ip", "user_agent", "accept_header" ] }, "Discount": { "title": "discount", "x-stoplight": { "id": "0dgp8etm5709j" }, "type": "string", "description": "Customer discount in two decimals applied to the transaction amount, if any" }, "Ds_transaction_id": { "title": "ds_transaction_id", "x-stoplight": { "id": "wceohqaji2zvf" }, "type": "string", "description": "Directory server transaction id for 3ds2.0", "example": "9ae6259e-08b8-42bb97a2-48d8a1d2a690", "pattern": "^[0-9a-f]{8}[1-5][0-9a-f]{3}[0-9a-f]{12}$" }, "Eci": { "title": "eci", "x-stoplight": { "id": "jq2g7i098vu5j" }, "type": "string", "description": "Authentication ECI indicator, as per the 3ds protocol (for V, M, D, A cards)" }, "End_date": { "title": "end_date", "x-stoplight": { "id": "uz968g6golwjt" }, "type": "string", "description": "Subscription end date in yyyy-mm-dd format\nNote: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years", "format": "date", "example": "2059-12-31" }, "Error_code": { "title": "error_code", "x-stoplight": { "id": "2grhtze0qf6ob" }, "type": "string", "description": "Represents the error code for the response" }, "Error_desc": { "title": "error_desc", "x-stoplight": { "id": "uyor3loffwtew" }, "type": "string", "description": "Represents the error description for the response" }, "Error_type": { "title": "error_type", "x-stoplight": { "id": "snpogojwqc0aq" }, "type": "string", "description": "Represents the error type for the response" }, "Frequency": { "title": "frequency", "x-stoplight": { "id": "xrmygt1ddb1b6" }, "type": "string", "description": "Frequency at which the subscription debits will be processed, possible values are:\n•week - weekly \n•mnth - monthly\n•bimn – bi-monthly\n•qurt - quarterly\n•bian – bi-annually\n•year - yearly\n•adho – adhoc\n", "enum": [ "week", "mnth", "bimn", "qurt", "bian", "year", "adho" ] }, "Holder_name": { "title": "holder_name", "x-stoplight": { "id": "azsrpizyvmymk" }, "type": "string", "description": "Cardholder name" }, "Invoice": { "type": "object", "x-examples": { "Example 1": { "invoice_number": "MEINVU111111221133", "invoice_display_number": "11221133", "customer_name": "John Doe", "invoice_date": "2021-09-03T13:21:50+05:30", "gst_details": { "cgst": "8.00", "sgst": "8.00", "igst": "0.00", "gst": "16.00", "cess": "0.00", "gstincentive": "5.00", "gstpct": "16.00", "gstin": "12344567" } } }, "properties": { "invoice_number": { "type": "string", "description": "Unique number assigned by merchant for the invoice", "pattern": "^[A-Za-z0-9]{1,100}$", "example": "MEINVU111111221133" }, "invoice_display_number": { "type": "string", "description": "Invoice number to be displayed to the customer", "example": "11221133", "pattern": "^[A-Za-z0-9]{1,80}$" }, "customer_name": { "type": "string", "pattern": "^[A-Za-z0-9]{1,80}$", "example": "John Doe", "description": "Customer's name to be printed on invoice" }, "invoice_date": { "type": "string", "description": "Invoice generation date in the YYYYMMDD format", "format": "date", "example": "2021-09-03" }, "gst_details": { "type": "object", "properties": { "cgst": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "100.00" }, "sgst": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "100.00" }, "igst": { "type": "string", "example": "200.00", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gst": { "type": "string" }, "cess": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$", "example": "50.00" }, "gstincentive": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gstpct": { "type": "string", "pattern": "^([0-9]{1}[0-9]{0,7}(\\\\.[0-9]{1,2})?)$" }, "gstin": { "type": "string", "pattern": "^[A-Za-z0-9]{1,80}$", "example": "29GGGGG1314R9Z6" } } } } }, "Itemcode": { "title": "item code", "x-stoplight": { "id": "tz16mo44yvoae" }, "type": "string", "description": "Itemcode value as provided by BillDesk, with a default value DIRECT", "example": "DIRECT", "pattern": "^[A-Za-z0-9]{1,20}$" }, "Links": { "type": "object", "x-stoplight": { "id": "7t5udyb6ilh37" }, "x-examples": { "Example 1": { "links": [ { "href": "https://wwww.issuerurl.com/somepage", "rel": "redirect", "method": "post", "parameters": { "creq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIzYjFlYmQ5NC04NTZhLTRlYjEtYTJlMS00MWZkNTdjZGFkZjAiLCJhY3NUcmFuc0lEIjoiOGMzMzk3NTItMjNmMS00NmZlLThmNzEtMzAwZjAyMzY0NjcxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0=" } } ] } }, "description": "Associated links with the object, and contains the issuer URL that will be provided in the redirect authentication workflow", "title": "links", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string", "description": "Issuer response URL" }, "rel": { "type": "string", "description": "Fixed value as redirect" }, "method": { "type": "string", "enum": [ "POST" ] }, "parameters": { "description": "Parameters that are used to redirect the customer to the issuer URL", "type": "object", "x-examples": { "Example 1": { "tranid": "973712065583009734440001099962", "AccuCardholderId": "90926094409", "AccuReturnURL": "https://www.merchanturl.com/response.jsp", "session": "U4440001099962", "AccuGuid": "15e66a3b-956e-42f8-84d4-859e3e8c9fed", "TermUrl": "https://www.merchanturl.com/response.jsp", "AccuRequestId": "YjIxM2ZiZGUyMGY2MmNjZWE5YWQ1NGE5OGNiZDUyZjkyYThlMDFiYjFkMTY1Yjc0ZTI4NTgxNDA1MGRiNzE0Ng==", "cardend": "4938" } }, "title": "parameters", "properties": { "creq": { "type": "string", "description": "Challenge request message or payment message for 3ds2.0 protocol authentication" }, "bdcreq": { "type": "string", "description": "Challenge request message or payment message for \n3ds2.0 protocol authentication (Threeds method url flow)" }, "tranid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuCardholderId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuReturnURL": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "session": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuGuid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuRequestId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } } } } } } }, "Links_Parameters": { "description": "Parameters that are used to redirect the customer to the issuer URL", "type": "object", "x-examples": { "Example 1": { "tranid": "973712065583009734440001099962", "AccuCardholderId": "90926094409", "AccuReturnURL": "https://www.merchanturl.com/response.jsp", "session": "U4440001099962", "AccuGuid": "15e66a3b-956e-42f8-84d4-859e3e8c9fed", "TermUrl": "https://www.merchanturl.com/response.jsp", "AccuRequestId": "YjIxM2ZiZGUyMGY2MmNjZWE5YWQ1NGE5OGNiZDUyZjkyYThlMDFiYjFkMTY1Yjc0ZTI4NTgxNDA1MGRiNzE0Ng==", "cardend": "4938" } }, "title": "parameters", "properties": { "creq": { "type": "string", "description": "Challenge request message or payment message for 3ds2.0 protocol authentication" }, "bdcreq": { "type": "string", "description": "Challenge request message or payment message for \n3ds2.0 protocol authentication (Threeds method url flow)" }, "tranid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuCardholderId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuReturnURL": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "session": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuGuid": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "TermUrl": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "AccuRequestId": { "type": "string", "description": "Payment parameter for rupay redirect flow" }, "cardend": { "type": "string", "description": "Payment parameter for rupay redirect flow" } } }, "Mandateid": { "title": "mandateid", "x-stoplight": { "id": "joq1b0hwy6hce" }, "type": "string", "description": "Unique mandateid created by BillDesk", "pattern": "^[A-Za-z0-9]{1,20}$", "example": "MA19E400049927" }, "Masked_value": { "title": "masked_value", "x-stoplight": { "id": "r3wddilt5cyy4" }, "type": "string", "description": "Masked card number, with the last four digits", "example": "xxxxxxxxxxxx1001" }, "Me_ref_id": { "title": "me_ref_id", "x-stoplight": { "id": "5gfw31bjgpf6x" }, "type": "string", "description": "Unique identifier for a merchant, defined by the acquiring bank as a 6 digit code", "example": "545963" }, "Mercid": { "title": "mercid", "x-stoplight": { "id": "43ns25lu1fyuc" }, "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID", "description": "Unique identifier as defined by BillDesk for each merchant" }, "Next_step": { "title": "next_step", "x-stoplight": { "id": "ayox9qr52qx6o" }, "type": "string", "description": "Refers to the action to be taken by the merchant, for eg. redirect or capture_otp", "enum": [ "redirect", "capture_otp", "3ds2_challenge", "3ds2_frictionless" ] }, "Objectid": { "title": "objectid", "x-stoplight": { "id": "bbwm8bhhbqd4r" }, "type": "string", "description": "String representing the object's type. Objects of the same type share the same value. ", "enum": [ "transaction", "authentication", "mandate", "invoice", "cardaccount", "validatevpa", "dispute", "settlement", "altid", "mandate_token", "accountvalidation", "refund" ] }, "Orderid": { "title": "orderid", "x-stoplight": { "id": "lmwrwf7xn6wq8" }, "type": "string", "description": "Unique ID generated by the merchant for each request", "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$", "example": "TEST0000009005" }, "Payment_category": { "title": "payment_category", "x-stoplight": { "id": "epd66eokga23s" }, "type": "string", "description": "Payment Category Code, defines the transaction belonging to the payment mode.\n• 00 - Card Gateway\n• 01 - Netbanking\n• 02 - Credit card\n• 03 - Debit card\n• 04 - Cash card\n• 05 - Mobile wallet\n• 10 - UPI\n• 11 - Bharat QR\n• 12 - Loan EMI\n• 13 - NEFT\n• 18 - UPI Credit\n• 19 - ENACH\n• 20 - CBDC\n• 21 - UPI Prepaid Wallet\n• 22 - UPI Credit Line", "example": "18" }, "Payment_method_type": { "title": "payment_method_type", "x-stoplight": { "id": "kklghqguq1r3q" }, "type": "string", "description": "Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option)\nThe associated object will also be provided in the request.", "enum": [ "card", "netbanking", "upi", "eft", "cardless", "bankaccount" ] }, "Recurrence_rule": { "title": "recurrence_rule", "x-stoplight": { "id": "mzu48wk4tb3i8" }, "type": "string", "description": "Note: Required only where payment_method_type = upi. Default value : 'after'\n", "enum": [ "after" ] }, "Refund_info": { "type": "object", "x-stoplight": { "id": "0a9154jkzqr2x" }, "properties": { "refundInfo": { "type": "array", "items": { "type": "object", "properties": { "refundid": { "type": "string", "description": "Unique id generated by BillDesk for the refund" }, "refund_amount": { "type": "string", "description": "Refund amount in two decimals" }, "currency": { "title": "currency", "x-stoplight": { "id": "1ehjh4f7vidz7" }, "type": "string", "description": "ISO currency code of the transaction amount, for INR this value will be 356" }, "refund_date": { "type": "string", "description": "BillDesk refund date and time in YYYY-MM-DDThh:mm:ssTZD format" }, "merc_refund_ref_no": { "type": "string", "description": "Unique reference number generated by the merchant for the refund request" }, "refund_status": { "type": "string", "description": "Represents the refund status with the following values:\n•\t0799 – categorized as a refund, where the original transaction has been already settled \n•\t0699 – categorized as a cancellation, where the original transaction has not been settled\n" } } } } }, "description": "" }, "Ru": { "title": "return URL", "x-stoplight": { "id": "2nnmkccdq26ck" }, "type": "string", "example": "https://www.merchant.com", "pattern": "=^(https?)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;{]*[-a-zA-Z0-9+&@#/%=~_|} ]{1,2000}$", "description": "Merchants URL where the customer will be redirected after a transaction is completed" }, "Rupay_auth_ref_no": { "title": "rupay_auth_ref_no", "x-stoplight": { "id": "p2pdfeb2zd0g6" }, "type": "string", "description": "Refers to the specific transaction reference provided by NPCI (for R cards)" }, "Split_payment_refund_request": { "type": "object", "x-stoplight": { "id": "715c0b8e1f0ab" }, "x-examples": { "Example 1": { "split_refund": [ { "mercid": "BDMERCID1", "txn_amount": "75.00", "refund_amount": "65.00" }, { "mercid": "BDMERCID2", "txn_amount": "25.00", "refund_amount": "25.00" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split refund amount will be adjusted", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID" }, "txn_amount": { "type": "string", "description": "Split Amount which was settled in the respective Split Merchant ID.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" }, "refund_amount": { "type": "string", "description": "Refund Amount against txn_amount.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" } }, "title": "" }, "Split_payment_refund_response": { "type": "object", "x-examples": { "Example 1": { "split_refund": [ { "mercid": "BDMERCID1", "txn_amount": "75.00", "refund_amount": "65.00", "refund_status": "0799" }, { "mercid": "BDMERCID2", "txn_amount": "25.00", "refund_amount": "25.00", "refund_status": "0699" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split refund amount will be adjusted" }, "txn_amount": { "type": "string", "description": "Split Amount which was settled in the respective Split Merchant ID." }, "refund_amount": { "type": "string", "description": "Refund Amount against txn_amount." }, "refund_status": { "type": "string", "description": "Represents the refund status of the transaction with the following possible values:\n•\t0799 - transaction is refunded\n•\t0699 - transaction is cancelled" } }, "description": "" }, "Split_payment_request": { "type": "object", "x-examples": { "Example 1": { "split_payment": [ { "mercid": "BDMERCID1", "amount": "3000.00" }, { "mercid": "BDMERCID2", "amount": "1000.00" } ] } }, "properties": { "mercid": { "type": "string", "description": "Merchant ID provided by BillDesk where split payment amount will be settled.", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "BDMERCID" }, "amount": { "type": "string", "description": "Split Amount which is settled in the respective Split Merchant ID.", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$", "example": "299.28" } }, "description": "This object is applicable in case a merchant has opted to receive the settlement in multiple settlement accounts", "title": "split_payment_request" }, "Start_date": { "title": "start_date", "x-stoplight": { "id": "v7tyy2tfnut1w" }, "type": "string", "description": "Subscription start date in yyyy-mm-dd format\nNote: Should be greater than or equal to current date (IST timezone). \nNote for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date \n", "format": "date", "example": "2021-05-08" }, "Subscription_amount": { "title": "subscription_amount", "x-stoplight": { "id": "7j61bmv2v1u41" }, "type": "string", "description": "Subscription amount in two decimals, eg. 2400.00", "example": "2400.00", "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$" }, "Subscription_desc": { "title": "subscription_desc", "x-stoplight": { "id": "lwkkeas7tgojy" }, "type": "string", "example": "Unlimited Plan", "description": "Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel" }, "Subscription_refid": { "title": "subscription_refid", "x-stoplight": { "id": "0c9vc4zqx4a8c" }, "type": "string", "example": "SUBREF101", "description": "Unique reference assigned by merchant for a subscription" }, "Subscription_status": { "title": "subscription_status", "x-stoplight": { "id": "y0fyz4zqhcknd" }, "type": "string", "description": "Represents the status of the mandate and depends upon the linked payment method. \n\nThe following values are possible:\ncard, upi\n•\tinitiated - mandate request has been initiated, and this status is applicable for the SDK based workflow\n•\tpending - mandate request has been initiated and the linked payment method is not yet validated\n•\tactive – linked payment method has been validated and recurring charges can be processed\n•\trejected - mandate has been rejected by the issuer or payment provider\n•\tdeleted - mandate has been deleted by the customer from the merchant channel\n•\tcancelled – mandate has been stopped by customer from the issuer channel\n•\tsuspended – mandate has been temporarily suspended by the issuer or payment provider\nbankaccount\n•\tpending – mandate request has been sent for account verification to NPCI\n•\tactive – mandate is active and recurring charges can be processed\n•\tdelete_initiated – mandate delete request is initiated by the customer or the merchant\n•\tdeleted – mandate is deleted after confirmation from NPCI\n•\trejected – mandate is rejected by NPCI\n" }, "Surcharge": { "title": "surcharge", "x-stoplight": { "id": "u8bi4pr2xista" }, "type": "string", "description": "Customer surcharge in two decimals applied to the transaction amount, if any" }, "Threeds_transaction_id": { "title": "threeds_transaction_id", "x-stoplight": { "id": "c54txyf8e8aqp" }, "type": "string", "description": "Threeds server transaction id", "format": "uuid", "example": "4184a9f8-b0f3-47d2-91ec-bc9939080e32" }, "Threeds_version": { "title": "threeds_version", "x-stoplight": { "id": "o8scvjfj8moas" }, "type": "string", "description": "Protocol of the 3ds2.0 version used for authentication\n", "enum": [ "2.1.0", "2.2.0" ] }, "Transaction_date": { "title": "transaction_date", "x-stoplight": { "id": "d0ekw0quxfwwu" }, "type": "string", "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format", "format": "date-time", "example": "2023-03-14T15:14:39+05:30" }, "Transactionid": { "title": "transactionid", "x-stoplight": { "id": "uqizgn6tyoqhg" }, "type": "string", "description": "Unique transactionid created by BillDesk ", "pattern": "^[A-Za-z0-9]{14,35}$", "example": "U4560001099939" }, "Txn_process_type": { "title": "txn_process_type", "x-stoplight": { "id": "lyz1n731cb596" }, "type": "string", "description": "Indicates transaction processing type, will be the following values:\nAFA payment\n•\tcard - 3ds or y3ds or 3ds_redirect\n•\tupi – collect, qr or intent\n•\tnetbanking – nb\n•\teft - offline\nRecurring payment\n•\tcard, upi, bankaccount – si", "example": "y3ds", "enum": [ "y3ds", "3ds", "collect", "intent", "qr", "nb", "eft", "si" ] }, "Upi-response": { "type": "object", "x-examples": { "Example 1": { "upi": { "vpa": "billdesk@upi", "masked_vpa": "xxxxxx@upi" } } }, "title": "upi-response", "description": "Response of upi object in case of upi collect flow", "properties": { "upi": { "type": "object", "properties": { "vpa": { "type": "string", "description": "unmasked value of vpa" }, "masked_vpa": { "type": "string", "description": "masked value of vpa" } } } } }, "Upi": { "type": "object", "x-stoplight": { "id": "5964437f54f97" }, "x-examples": { "Example 1": { "vpa": "testvpa@abc" } }, "properties": { "vpa": { "type": "string", "description": "Virtual Payment Address", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\\\.\\\\-\\\\_]{2,38}\\\\@[a-zA-Z0-9]{3,20}$", "example": "abc@okbank" } }, "description": "Required when payment_method_type = upi and txn_process_type = collect" } } }, "tags": [ { "name": "Dispute" }, { "name": "Order" }, { "name": "Refund" }, { "name": "Settlement" }, { "name": "Transaction" } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } }