> This page is for Enterprise. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://citi-demo.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://citi-demo.ferndocs.com/_mcp/server. # Initiate An eMandate POST https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation Content-Type: application/json The eMandate Initiation API is sent by an initiating party (Creditor)to the receiving party (Debtor) in the collection chain to register an eMandate. CitiConnect clients can initiate eMandate Initiation for the direct debit collections. Currently, this functionality is applicable for the UK and for SEPA countries. The eMandate request will be sent in JSON message. The Push Notification API will enable eMandate API clients to receive proactive notification via a JSON Mandate Status Report if their Mandate Creation status changes. The push notification will only be sent for mandates initiated via API and client will receive multiple JSON Mandate Status Reports based on mandate status movement.\Content-Type: Supports 'application/json'Authorization: The OAuth Token prefixed with “Bearer“ and space in between. Reference: https://citi-demo.ferndocs.com/enterprises/api-reference/payment-acceptance/direct-debit/e-mandate-api/e-mandate-initiation ## Authentication - `Authorization` header (bearer token, required) — All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See the Citi Authentication API reference for information on requesting a token. ## Request ### Query parameters - `client_id` (string, required) — This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation ### Headers - `Authorization` (string, required) — The OAuth Token prefixed with "Bearer" and space in between. - `region` (string, required) — Specifies merchant's region from where the mandate request is initiated i.e. 'EMEA'. ### Body (application/json) This endpoint expects a mandate_full_details. - `mandate_details` (mandate_details, required) — Set of elements used to provide the details of the mandate signed between the (ultimate) creditor and the (ultimate) debtor. - `debtor` (party, required) — Account details about the party who initiates this payment. - `creditor` (party, required) — Account details about the party who receives this payment. - `scheme` (scheme_definition, optional) — Require for SEPA and BACS e-Mandate creation. Account details about the party who initiates this payment. ## Response ### 200 OK - `mandate_acceptance` (list of acceptance_detail, required) — Indicates whether the mandate request was accepted or rejected or in-progress. Accepted - 'Yes'In-Progress, Rejected - 'No'Possible DDI status for BACS -'Active', 'Cancelled', 'Complete', 'Pending', 'Ready for Export', 'Exported' Possible DDI status for SEPA -'Active', 'Cancelled', 'Complete', 'Pending' Possible Mandate status for HK - 'Processed', 'CB-Rejected', 'Deleted' ## Errors ### 400 Bad Request Error Bad Request - `errors` (list of error_detail, optional) - `links` (list of link, optional) - `status` (string, optional) — HTTP method for above URI. Possible values are GET, POST, PUT, DELETE - `mandate_request_identification` (string, optional) — Mandate request identification ### 401 Unauthorized Error Unauthorized - `errors` (list of error_detail, optional) - `links` (list of link, optional) - `status` (string, optional) — HTTP method for above URI. Possible values are GET, POST, PUT, DELETE - `mandate_request_identification` (string, optional) — Mandate request identification ### 405 Method Not Allowed Error Method Not Allowed - `errors` (list of error_detail, optional) - `links` (list of link, optional) - `status` (string, optional) — HTTP method for above URI. Possible values are GET, POST, PUT, DELETE - `mandate_request_identification` (string, optional) — Mandate request identification ### 415 Unsupported Media Type Error Unsupported Media Type - `errors` (list of error_detail, optional) - `links` (list of link, optional) - `status` (string, optional) — HTTP method for above URI. Possible values are GET, POST, PUT, DELETE - `mandate_request_identification` (string, optional) — Mandate request identification ### 500 Internal Server Error Internal Server Error - `errors` (list of error_detail, optional) - `links` (list of link, optional) - `status` (string, optional) — HTTP method for above URI. Possible values are GET, POST, PUT, DELETE - `mandate_request_identification` (string, optional) — Mandate request identification ## Types ### mandate_details - `mandate_request_identification` (string, required) — Unique identification, as assigned by the creditor, to unambiguously identify the mandate.For SEPA max of 35 characters can be used.Recommendation for BACS: Merchant to assign max of 14 chars as Mandate Reference.InBacs, EndToEnd Identifier = Mandate Reference + 4 random chars for uniqueness.The4 characters would enable Sentenial to build unique end to end reference for the DDs. - `mandate_occurence` (occurence, required) - `mandate_type` (mandate_codes, required) — Specifies the type of mandate, such as paper, electronic or scheme. - `mandate_identification` (string, optional) — Unique identification, as assigned by the creditor, to unambiguously identify the mandate.For SEPA max of 35 characters can be used.Recommendation for BACS: Merchant to assign max of 14 chars as Mandate Reference.In Bacs, EndToEnd Identifier = Mandate Reference + 4 random chars for uniqueness.The4 characters would enable Sentenial to build unique end to end reference for the DDs.For IN-UPI ID: It is mandatory to mention the payee UPIID for creating mandate. - `tracking_indicator` (boolean, optional) — Require for SEPA and BACS clients. Specifies whether the directdebit instructions should be automatically re-submitted periodically when bilaterally agreed. Recommendation : To be used as Migrating mandate indicator. True - mandate will be treated as a migrating mandate. False - mandate will be treated as a new mandate. - `token_identification_type` (string, optional) — Require for HK. Specify the value only when the Mandate request is other than Payer(Debtor) Account Number.Specify the Possible Values as mentioned belowIf Token ID Type is 'Proxy ID - Email Address then populate the Code :'EMAL'If Token ID Type is 'Credit Card Number' then populate the code- 'AIIN'If Token ID Type is 'Proxy ID - FPSIdentifier' then populate the code- 'SVID'If Token ID Type is 'ProxyID - Mobile Number' then populate the code- 'MOBN'. - `token_identification` (string, optional) — Require for HK. Identification used to indicate the accountidentification under another specified name.If Token ID Type is 'CreditCard Number' then specify the 'AIIN' ValueIf Token ID Type is 'ProxyID - FPS Identifier' then specify the 'SVID' ValueIf Token ID Typeis 'Proxy ID - Mobile Number' then specify the 'MOBN' ValueIf TokenID Type is 'Proxy ID - Email Address' then specify the 'EMAL' Value. - `mandate_start_date` (string, optional) — Require for IN.This includes start date of the mandate. - `mandate_expiry_date` (string, optional) — Require for HK & IN.Length of time for which the mandate remains valid.Specify the expiry date of the mandate Maximum date supported: 9999-12-31.A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. - `mandate_reference` (reference, optional) — Require for HK. Specifies the type of mandate, such as paper, electronic or scheme. - `mandate_transactions` (transaction_info, optional) — Require for HK e-mandate creation. Transaction details for themandate which is requested for creation ### party - `name` (string, required) — Name by which a party is known and which is usually used to identify that party.Note for BACS client: Only 18 characters are allowed for party names in the files submitted to BACS scheme.Sentenial would take request up to 70 chars but only first 18 chars would be used and send to the scheme. - `account` (account, required) — A valid IBAN consists of all three of the following components:Country Code, check digits and BBAN. BACS Usage Rule(s) - EitherIBAN or Domestic Account number is allowed. SEPA Usage Rule(s) -Only IBAN is allowed. - `identification` (list of PartyIdentificationItems, optional) - `address` (address, optional) — Address of the party who involves in the payment flow\.Applicable only for Creditor. BACS Rule(s) - Debtor Postal Address is never passed in the files to the scheme. SEPA Usage Rule(s) - Postal Address is optional but mandatory if or when the Creditor Bank or the Debtor Bank is located in a non-EEA SEPA country or territory. - `contact` (contact, optional) — Collection of information that identifies a mobile phone number, FAX number as defined by telecom services. Mobile Number Format- Full international dialing code to be provided. - No non-numeric characters allowed - GB phone number +44 28 123 4567 would need to be provided as 44281234567. ### scheme_definition - `identification` (string, required) — Originator Creditor Scheme Identifier.For BACS SUN number to be inputted, A Service User Number (SUN) is a unique six-digit number allocated to a Service User collecting payments by Direct Debit. SUN number should be of 6-digits only. You can think of it as a license given from a bank to a business/organization to join the Direct Debit scheme. - `type` (string, required) — Should be inputted as 'SEPA' or 'BACS'. Not required forHK. - `name` (string, required) — Name of the identification scheme, in a free text form. - `classification` (string, optional) — Defines Creditor or Debtor Scheme classification. For SEPA, BACS, and HK only Creditor scheme is applicable for now. Allowed values are CR or DR. - `private_identification` (string, optional) — Private Identification’ is mandatory to identify either an organization or a private person. ### acceptance_detail - `accepted` (string, required) — Indicates whether the mandate request was accepted or rejected.Accepted - 'Yes' In-Progress, Rejected - 'No' - `mandate_request_identification` (string, required) — Encoded resource ID from Sentenial, which must be used for Inquiring Mandate. - `reasons` (list of reason, required) — Reasons to populate when mandate rejected. - `scheme_identification` (string, required) — Encoded scheme ID from Sentenial, which must be used for Inquiring mandate. - `mandate_identification` (string, optional) — Mandate Id is to retreive the status of mandate. ### error_detail - `action` (string, optional) — What corrective action to be taken to resolve above issue. - `issue` (string, optional) — More details about the issue. ### link - `href` (string, optional) — URI for related operation - `method` (string, optional) — HTTP method for above URI. Possible values are GET, POST, PUT, DELETE. - `rel` (string, optional) — How this is related to current resource. ### occurence - `sequence_type` (string, required) — Required for SEPA, BACS & IN. Identifies the underlying transaction sequence as either recurring or one-off. For BACS Only ‘RCUR’ to be allowed.SEPA Usage rules only FRST, RCUR, FNAL,OOFF is allowed. For IN also OOFF is possible (In case the mandate is ‘One Time’ debit can be initiated only once by the Payee PSP. ‘One time’ mandate supports an additional functionality called ‘Share with Payee’. If this tag is NOT SET by the Payer (User) then Payee PSP will NOT share the information about the mandate creation with Payee (User at the receiving end). - `frequency` (string, required) — Required for Hk & IN. Frequency expressed as an ISO 20022 code.For HK & IN Possible Values: YEAR – AnnualMNTH – MonthlyQURT – QuarterlyMIAN– Semi AnnualWEEK – WeeklyDAIL – Daily ### mandate_codes - `local_instrument` (codeOrProprietary, required) — User community specific instrument.This element is used to specifya local instrument, local clearing option and/or further qualify the serviceor service level.For BACS only 'CORE’ to be used. SEPAUsage Rule(s) Only ‘CORE’ or 'B2B' is allowed.For HK Specify the MandateType code as 'DDMU'- Direct Debit Unconfirmed Electronic Mandate. - `service_level` (codeOrProprietary, required) — Specifies a pre-agreed service or level of service between theparties, as published in an external service level code list.ForBACS only 'BACS' to be used.SEPA Usage Rule(s) Only ‘SEPA’ isallowed. ### reference - `payer_reference_number` (string, optional) — Unique and unambiguous identification as assigned by the creditor to the referred document shared with the debtor for its own reference.Specify the reference document for the mandate, to be referred by debtor. - `payer_code` (string, optional) — Proprietary identification of the type of the remittance document.Specifythe code 'PAYC' followed by the value. - `payment_reference_number` (list of string, optional) ### transaction_info - `cumulative_amount` (double, required) — Specify cumulative fixed amount to be collected from the debtor's account. - `amount` (double, optional) — Maximum amount that may be collected from the debtor's account, per instruction.Amount of the transaction. Determine how and when a currency fractional (decimals) should be indicated in each transaction. Maximum of 15 Digits (Including decimals). - `rule` (string, optional) — Require for IN. To specify amount & amount rule: Amountrule can will have either 'MAX' or 'EXACT' as the values. - `count` (double, optional) — Specify the number of instructions to be created and processed during the specified period. ### account - `currency_code` (string, required) — For HK, Specify creditor account Currency - HKD / CNY.Account Currency should be Citi client account currency. - `bic` (string, required) — Code allocated to a financial institution by the ISO 9362 RegistrationAuthority as described in ISO 9362 Banking - Banking telecommunicationmessages - Business identifier code (BIC). - `branch_country` (string, required) — Require for HK. To identify the Bank branch country. - `identification` (string, optional) — For BACS either IBAN or Domestic Account number can be used.Avalid Domestic account number includes Branch Identifier(6 digits) andAcccount number(8 digits). - `iban` (string, optional) — SEPA Usage Rule(s) - Only IBAN is allowed. InternationalBank Account Number (IBAN) - identifier used internationally by financialinstitutions to uniquely identify the account of a customer For SEPA.International Bank Account Number (IBAN) - identifier used internationallyby financial institutions to uniquely identify the account of a customer.Further specifications of the format andcontent of the IBAN can be foundin the standard ISO 13616 Banking and related financial services -InternationalBank Account Number (IBAN) version 1997-10-01, or later revisions.A valid IBAN consists of all three of the following components: CountryCode, check digits and BBAN. ### PartyIdentificationItems - `id` (string, optional) — Unique and unambiguous way to identify an organisation.Identificationassigned by an institution.IF COID = Provide Business Registrationnumber.IF CINC = Provide Certificate of Incorporation numberIFNIDN = Provide Hong Kong Identification- 'HKID' number IF CCPT-Provide Passport Number If OTHR= Provide the corresponding IDnumber and Require for HK. - `type` (string, optional) — Require for HK. Name of the identification scheme, in a coded form as published in an external list.Specify the respective code of the debtor identification as below:If 'Business Registration use code as = 'COID'If 'Certificate of Incorporation' use code as = 'CINC'If (Hong Kong Identification) 'HKID' use code as = 'NIDN'If 'Passport' = use code as = 'CCPT'If any other Identification (can be respective ) use code = 'OTHR'. ### address - `address_line_1` (string, optional) — Information that locates and identifies a specific address, as defined by postal services, presented in free format text. - `address_line_2` (string, optional) — Information that locates and identifies a specific address,as defined by postal services, presented in free format text. - `town_name` (string, optional) — Name of a built-up area, with defined boundaries, and a localgovernment. - `postal_code` (string, optional) — Identifier consisting of a group of letters and/or numbers thatis added to a postal address to assist the sorting of mail. - `country_code` (string, optional) — Country of the Creditor address. Must be a valid countrycode according to ISO3166 alpha -2 'Postal Address’ is optional butCountry element mandatory if 'Postal Address provided by the Creditor. ### contact - `mobile_number` (string, optional) — Collection of information that identifies a mobile phone number, as defined by telecom services. Mobile Number Format - Full international dialling code to be provided. - No non-numeric characters allowed- GB phone number +44 28 123 4567 would need to be provided as 44281234567 - `fax_number` (string, optional) — Collection of information that identifies a FAX number, as definedby telecom services. - `email` (string, optional) — Address for electronic mail (e-mail). string \<= 254 characters.*@.* ### reason - `code` (string, optional) — Reason, as published in an external reason code list. ExternalMandateReason1Code Cannot be used at the same time as reason\_properitory (below) (schemavalidation). - `description` (string, optional) — Reason, in a description form. Cannot be used at the same time as reason\_code (above) (schema validation). ### codeOrProprietary - `code` (string, optional) — This element is used to specify a local instrument, local clearingoption and/or further qualify the service or service level. - `proprietary` (string, optional) — Citi Proprietary definition for local instrument code. ## Examples **Request** ```json { "mandate_details": { "mandate_request_identification": "string", "mandate_occurence": { "sequence_type": "string", "frequency": "string" }, "mandate_type": { "local_instrument": {}, "service_level": {} } }, "debtor": { "name": "string", "account": { "currency_code": "string", "bic": "string", "branch_country": "string" } }, "creditor": { "name": "string", "account": { "currency_code": "string", "bic": "string", "branch_country": "string" } } } ``` **Response** ```json { "mandate_acceptance": [ { "accepted": "NO", "mandate_request_identification": "e27kpp59yb", "reasons": [ { "code": "PDNG", "description": "READY_FOR_EXPORT" } ], "scheme_identification": "w24no84ybp", "mandate_identification": "test2402" } ] } ``` **SDK Code** ```python response import requests url = "https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation" querystring = {"client_id":"client_id"} payload = { "mandate_details": { "mandate_request_identification": "string", "mandate_occurence": { "sequence_type": "string", "frequency": "string" }, "mandate_type": { "local_instrument": {}, "service_level": {} } }, "debtor": { "name": "string", "account": { "currency_code": "string", "bic": "string", "branch_country": "string" } }, "creditor": { "name": "string", "account": { "currency_code": "string", "bic": "string", "branch_country": "string" } } } headers = { "Authorization": "Bearer ", "region": "region", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript response const url = 'https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id'; const options = { method: 'POST', headers: { Authorization: 'Bearer ', region: 'region', 'Content-Type': 'application/json' }, body: '{"mandate_details":{"mandate_request_identification":"string","mandate_occurence":{"sequence_type":"string","frequency":"string"},"mandate_type":{"local_instrument":{},"service_level":{}}},"debtor":{"name":"string","account":{"currency_code":"string","bic":"string","branch_country":"string"}},"creditor":{"name":"string","account":{"currency_code":"string","bic":"string","branch_country":"string"}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go response package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id" payload := strings.NewReader("{\n \"mandate_details\": {\n \"mandate_request_identification\": \"string\",\n \"mandate_occurence\": {\n \"sequence_type\": \"string\",\n \"frequency\": \"string\"\n },\n \"mandate_type\": {\n \"local_instrument\": {},\n \"service_level\": {}\n }\n },\n \"debtor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n },\n \"creditor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("region", "region") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby response require 'uri' require 'net/http' url = URI("https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["region"] = 'region' request["Content-Type"] = 'application/json' request.body = "{\n \"mandate_details\": {\n \"mandate_request_identification\": \"string\",\n \"mandate_occurence\": {\n \"sequence_type\": \"string\",\n \"frequency\": \"string\"\n },\n \"mandate_type\": {\n \"local_instrument\": {},\n \"service_level\": {}\n }\n },\n \"debtor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n },\n \"creditor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java response import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id") .header("Authorization", "Bearer ") .header("region", "region") .header("Content-Type", "application/json") .body("{\n \"mandate_details\": {\n \"mandate_request_identification\": \"string\",\n \"mandate_occurence\": {\n \"sequence_type\": \"string\",\n \"frequency\": \"string\"\n },\n \"mandate_type\": {\n \"local_instrument\": {},\n \"service_level\": {}\n }\n },\n \"debtor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n },\n \"creditor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n }\n}") .asString(); ``` ```php response request('POST', 'https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id', [ 'body' => '{ "mandate_details": { "mandate_request_identification": "string", "mandate_occurence": { "sequence_type": "string", "frequency": "string" }, "mandate_type": { "local_instrument": {}, "service_level": {} } }, "debtor": { "name": "string", "account": { "currency_code": "string", "bic": "string", "branch_country": "string" } }, "creditor": { "name": "string", "account": { "currency_code": "string", "bic": "string", "branch_country": "string" } } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'region' => 'region', ], ]); echo $response->getBody(); ``` ```csharp response using RestSharp; var client = new RestClient("https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("region", "region"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"mandate_details\": {\n \"mandate_request_identification\": \"string\",\n \"mandate_occurence\": {\n \"sequence_type\": \"string\",\n \"frequency\": \"string\"\n },\n \"mandate_type\": {\n \"local_instrument\": {},\n \"service_level\": {}\n }\n },\n \"debtor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n },\n \"creditor\": {\n \"name\": \"string\",\n \"account\": {\n \"currency_code\": \"string\",\n \"bic\": \"string\",\n \"branch_country\": \"string\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift response import Foundation let headers = [ "Authorization": "Bearer ", "region": "region", "Content-Type": "application/json" ] let parameters = [ "mandate_details": [ "mandate_request_identification": "string", "mandate_occurence": [ "sequence_type": "string", "frequency": "string" ], "mandate_type": [ "local_instrument": [], "service_level": [] ] ], "debtor": [ "name": "string", "account": [ "currency_code": "string", "bic": "string", "branch_country": "string" ] ], "creditor": [ "name": "string", "account": [ "currency_code": "string", "bic": "string", "branch_country": "string" ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://tts.apib2b.citi.com/citiconnect/prod/emandateservices/v2/emandateinitiation?client_id=client_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```