--- updatedAt: 2025-11-10T23:33:58.000Z agentTools: projectIndex: https://docs.billdesk.io/llms.txt --- # Create Transaction This endpoint creates a new transaction to initiate a charge using a payment method. # OpenAPI definition ```json { "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/transactions/create": { "post": { "summary": "Create Transaction", "description": "This endpoint creates a new transaction to initiate a charge using a payment method.", "operationId": "createTransaction", "parameters": [ { "$ref": "#/components/parameters/bdTraceId" }, { "$ref": "#/components/parameters/bdTimeStamp" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "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": { "$ref": "#/components/schemas/Objectid" }, "transactionid": { "$ref": "#/components/schemas/Transactionid" }, "orderid": { "$ref": "#/components/schemas/Orderid" }, "mercid": { "$ref": "#/components/schemas/Mercid" }, "transaction_date": { "$ref": "#/components/schemas/Transaction_date" }, "amount": { "$ref": "#/components/schemas/Amount" }, "surcharge": { "$ref": "#/components/schemas/Surcharge" }, "discount": { "$ref": "#/components/schemas/Discount" }, "charge_amount": { "$ref": "#/components/schemas/Charge_amount" }, "currency": { "$ref": "#/components/schemas/Currency" }, "ru": { "$ref": "#/components/schemas/Ru" }, "txn_process_type": { "$ref": "#/components/schemas/Txn_process_type" }, "bankid": { "$ref": "#/components/schemas/Bankid" }, "itemcode": { "$ref": "#/components/schemas/Itemcode" }, "auth_status": { "$ref": "#/components/schemas/Auth_status" }, "transaction_error_code": { "$ref": "#/components/schemas/Error_code" }, "transaction_error_desc": { "$ref": "#/components/schemas/Error_desc" }, "transaction_error_type": { "$ref": "#/components/schemas/Error_type" }, "payment_method_type": { "$ref": "#/components/schemas/Payment_method_type" }, "next_step": { "$ref": "#/components/schemas/Next_step" }, "card": { "$ref": "#/components/schemas/Cardaccount-in-txn-response" }, "additional_info": { "$ref": "#/components/schemas/Additional-Info" }, "links": { "$ref": "#/components/schemas/Links" }, "avs": { "$ref": "#/components/schemas/Avs-response" }, "mandate": { "$ref": "#/components/schemas/Mandate-Response" }, "upi": { "$ref": "#/components/schemas/Upi-response" }, "payment_category": { "$ref": "#/components/schemas/Payment_category" }, "me_ref_id": { "$ref": "#/components/schemas/Me_ref_id" } } }, "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": { "$ref": "#/components/schemas/Error-object" }, "examples": { "Forbidden": { "$ref": "#/components/examples/403-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" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error-object" }, "examples": { "Internal Server Error": { "$ref": "#/components/examples/500-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": { "$ref": "#/components/schemas/Error-object" }, "examples": { "Invalid merchant config": { "$ref": "#/components/examples/422-Invalid-merchant-config" } } } }, "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": { "$ref": "#/components/schemas/Mercid" }, "orderid": { "$ref": "#/components/schemas/Orderid" }, "amount": { "$ref": "#/components/schemas/Amount" }, "bankid": { "$ref": "#/components/schemas/Bankid" }, "currency": { "$ref": "#/components/schemas/Currency" }, "ru": { "$ref": "#/components/schemas/Ru" }, "authentication_type": { "$ref": "#/components/schemas/Authentication_type" }, "3ds_parameter": { "$ref": "#/components/schemas/3ds_parameter" }, "txn_process_type": { "$ref": "#/components/schemas/Txn_process_type" }, "itemcode": { "$ref": "#/components/schemas/Itemcode" }, "device": { "$ref": "#/components/schemas/Device" }, "payment_method_type": { "$ref": "#/components/schemas/Payment_method_type" }, "card": { "oneOf": [ { "$ref": "#/components/schemas/Pay-using-card-number-pan" }, { "$ref": "#/components/schemas/Pay-using-network-token" }, { "$ref": "#/components/schemas/Pay-using-issuer-token" }, { "$ref": "#/components/schemas/Pay-using-card-account-id" }, { "$ref": "#/components/schemas/Pay-using-altid" } ] }, "customer_refid": { "$ref": "#/components/schemas/Customer_refid" }, "avs": { "$ref": "#/components/schemas/Avs-request" }, "mandate": { "$ref": "#/components/schemas/Mandate" }, "upi": { "$ref": "#/components/schemas/Upi" }, "additional_info": { "$ref": "#/components/schemas/Additional-Info" } }, "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" ] } } }, "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" } }, "examples": { "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" } }, "422-Invalid-merchant-config": { "value": { "status": 422, "error_type": "api_validation_error", "error_code": "GNAVE0001", "message": "Incorrect merchant configuration" } } }, "schemas": { "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" } } }, "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": { "$ref": "#/components/schemas/Start_date" }, "end_date": { "$ref": "#/components/schemas/End_date" }, "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": { "$ref": "#/components/schemas/Amount_type" }, "recurrence_rule": { "$ref": "#/components/schemas/Recurrence_rule" }, "debit_day": { "$ref": "#/components/schemas/Debit_day" } }, "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" ] }, "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" ] }, "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" }, "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": { "$ref": "#/components/schemas/Bankacc_number", "description": "Customer's bank account number" }, "ifsc": { "$ref": "#/components/schemas/IFSC", "description": "IFSC of the bank account number" }, "name": { "$ref": "#/components/schemas/Bankaccount_holder_name", "description": "Name of the bank account holder" } }, "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": { "$ref": "#/components/schemas/Bankacc_number" }, "ifsc": { "$ref": "#/components/schemas/IFSC" }, "name": { "$ref": "#/components/schemas/Bankaccount_holder_name" } } } }, "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": "" }, "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": { "$ref": "#/components/schemas/Masked_value" }, "type": { "$ref": "#/components/schemas/Card_type" }, "card_end": { "type": "string" }, "network": { "$ref": "#/components/schemas/Card_network" }, "issuer": { "$ref": "#/components/schemas/Card_issuer" }, "cardaccountid": { "$ref": "#/components/schemas/Cardaccountid" }, "coft_consent": { "type": "string" }, "cardaccount": { "type": "object", "properties": { "objectid": { "$ref": "#/components/schemas/Objectid" }, "mercid": { "$ref": "#/components/schemas/Mercid" }, "customer_refid": { "$ref": "#/components/schemas/Customer_refid" }, "cardaccountid": { "type": "string" }, "orderid": { "$ref": "#/components/schemas/Orderid" }, "masked_value": { "type": "string" }, "holder_name": { "$ref": "#/components/schemas/Holder_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": { "$ref": "#/components/schemas/Error_code" }, "cardaccount_error_type": { "$ref": "#/components/schemas/Error_type" }, "cardaccount_error_desc": { "$ref": "#/components/schemas/Error_desc" } } } }, "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" }, "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" }, "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" ] }, "Discount": { "title": "discount", "x-stoplight": { "id": "0dgp8etm5709j" }, "type": "string", "description": "Customer discount in two decimals applied to the transaction amount, if any" }, "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" }, "Holder_name": { "title": "holder_name", "x-stoplight": { "id": "azsrpizyvmymk" }, "type": "string", "description": "Cardholder name" }, "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": { "$ref": "#/components/schemas/Links_Parameters", "description": "Parameters that are used to redirect the customer to the issuer URL" } } } } } }, "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" } } }, "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" ] }, "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" }, "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" }, "Surcharge": { "title": "surcharge", "x-stoplight": { "id": "u8bi4pr2xista" }, "type": "string", "description": "Customer surcharge in two decimals applied to the transaction amount, if any" }, "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": "Transaction" } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```