--- title: "Create mandate" method: POST path: "/v3/mandates" tags: ["Mandates"] --- # Create mandate `POST /v3/mandates` ## Request - Base URL: `https://api.truelayer-sandbox.com` - URL: `https://api.truelayer-sandbox.com/v3/mandates` - Auth: OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `mandates` Create a new mandate This API must be called using a backend bearer token. ## Headers - `Idempotency-Key` string, required - `Tl-Signature` string, required ## Request body - CreateMandate - `mandate` union, required - MandateVRPSweeping - `type` 'sweeping', required: The type of VRP mandate that will be created. - `provider_selection` union, required: Provider Selection - object: Indicates that the provider is to be selected from a collection - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilter: Configuration options to constrain which providers should be available during the `provider_selection` action. - `countries` CountryCode[]: Only providers from the specified countries will be returned. - `release_channel` 'general_availability' | 'public_beta' | 'private_beta': The lowest stability release stage of a provider that should be returned. Note that many EUR providers are in `public_beta` or `private_beta`. - `customer_segments` string[]: The customer segments that providers cater to that should be returned. By default, returns retail only. - `provider_ids` string[]: IDs of providers to include in those returned. - `excludes` object: Options to exclude providers included by the filters - … - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `remitter` Remitter: Remitter - `account_holder_name` string, required: The name of the external account holder. pattern: `^[^\(\)]{1,80}$` - `account_identifier` union, required: A unique account identifier for an external account. - … - `beneficiary` union, required - MandateDestinationMerchantAccount: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string, uuid, required: Unique ID for the Merchant Account - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - MandateDestinationExternalAccount: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. This should not be more than 18 characters and shouldn’t contain [special characters](https://docs.truelayer.com/docs/character-limitations-in-payments#special-characters) - `account_identifier` union, required: A unique account identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierBban: Basic bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - `reference` string: A custom reference for the mandate, available for regulated customers only. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]{1,18}$`. If not specified, one is automatically set to be your application's name, adjusted as needed. This field is deprecated. Please use the `statement_reference` field instead. - `statement_reference` string: A custom reference for the mandate, available for regulated customers only. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]{1,18}$`. If not specified, one is automatically set to be your application's name, adjusted as needed. - MandateVRPCommercial - `type` 'commercial', required: The type of VRP mandate that will be created. - `use_case` 'charity' | 'financial_services' | 'government' | 'utilities', required: The use case for which the cVRP mandate is used for. - `provider_selection` union, required: Provider Selection - object: Indicates that the provider is to be selected from a collection - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilter: Configuration options to constrain which providers should be available during the `provider_selection` action. - `countries` CountryCode[]: Only providers from the specified countries will be returned. - `release_channel` 'general_availability' | 'public_beta' | 'private_beta': The lowest stability release stage of a provider that should be returned. Note that many EUR providers are in `public_beta` or `private_beta`. - `customer_segments` string[]: The customer segments that providers cater to that should be returned. By default, returns retail only. - `provider_ids` string[]: IDs of providers to include in those returned. - `excludes` object: Options to exclude providers included by the filters - … - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `remitter` Remitter: Remitter - `account_holder_name` string, required: The name of the external account holder. pattern: `^[^\(\)]{1,80}$` - `account_identifier` union, required: A unique account identifier for an external account. - … - `beneficiary` union, required - MandateDestinationMerchantAccount: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string, uuid, required: Unique ID for the Merchant Account - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - MandateDestinationExternalAccount: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. This should not be more than 18 characters and shouldn’t contain [special characters](https://docs.truelayer.com/docs/character-limitations-in-payments#special-characters) - `account_identifier` union, required: A unique account identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierBban: Basic bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - `reference` string: A custom reference for the mandate, available for regulated customers only. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]{1,18}$`. If not specified, one is automatically set to be your application's name, adjusted as needed. This field is deprecated. Please use the `statement_reference` field instead. - `statement_reference` string: A custom reference for the mandate, available for regulated customers only. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]{1,18}$`. If not specified, one is automatically set to be the clients name, adjusted as needed. - MandateDirectDebit - `type` 'direct_debit', required: The type of mandate that will be created. > 📘 > > Direct debits are in beta. Please contact us to learn more. - `remitter` union, required - object: Remitter - `type` 'preselected' - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `account_holder_name` string, required: The name of the external account holder. pattern: `^[^\(\)]{1,80}$` - `account_identifier` union, required: A unique account identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierBban: Basic bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - object - `type` 'payment_source_provided', required - `initial_payment` DDInitialPayment - `amount_in_minor` integer, required: A 'cent' value representing the amount, e.g. 100 == 1GBP or 100 = 1EUR - `provider_selection` union, required: Provider Selection - object: Indicates that the provider is to be selected from a collection - … - object: Preselected provider. Indicates that the provider for this payment is preselected. - … - `beneficiary` DDBeneficiary, required: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string, uuid, required: Unique ID for the Merchant Account - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `currency` 'GBP' | 'EUR', required - `user` PaymentUserCreate, required: Details of the end user who is making the payment. If you are using your own PISP licence, these fields are not required. Payments over a mandate don't need user information as this was collected at mandate creation. - `id` string: Unique ID for the User - `name` string: This is the full first and last name of your end user (not initials). If you are using your own PISP licence this field is optional, otherwise it is required. pattern: `^[^\(\)]+$` - `email` string, email: The email address of your end user according to [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822). If you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required. - `phone` string, phone: The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`. If you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required. - `date_of_birth` string, date: The date of birth of your end user, in `YYYY-MM-DD` format. - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `political_exposure` 'current' | 'none': The user's political exposure (PEP), if known this field should be set to `current` otherwise to `none`. If not known this field can be ignored or a `null` value can be sent. - `constraints` VRPConstraints: Sets the limits for the payments that can be created by the mandate. If a payment is attempted that doesn't fit within these constraints it will fail. These constraints are considered only for VRP mandates (not direct debit). - `valid_from` string, datetime: Start date time for which the consent remains valid using format `YYYY-MM-DDTHH:mm:ss.sssZ` - `valid_to` string, datetime: End date time for which the consent remains valid using format `YYYY-MM-DDTHH:mm:ss.sssZ` - `maximum_individual_amount` integer, required: A 'cent' value representing the maximum amount that can be specified in a payment instruction - `periodic_limits` object, required: The limits for the payments that can be created by the mandate within a specified time period. At least one periodic limit must be provided upon mandate creation. - `day` object: Limit for payments made within a day - `maximum_amount` integer, required: A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period. `maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified. - `period_alignment` 'consent' | 'calendar', required: Specifies whether the period starts on the date of consent creation or lines up with a calendar. If the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days. - `week` object: Limit for payments made within a week - `maximum_amount` integer, required: A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period. `maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified. - `period_alignment` 'consent' | 'calendar', required: Specifies whether the period starts on the date of consent creation or lines up with a calendar. If the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days. - `fortnight` object: Limit for payments made within a fortnight Only supports `period_alignment` of `consent`. - `maximum_amount` integer, required: A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period. `maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified. - `period_alignment` 'consent' | 'calendar', required: Specifies whether the period starts on the date of consent creation or lines up with a calendar. If the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days. - `month` object: Limit for payments made within a month - `maximum_amount` integer, required: A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period. `maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified. - `period_alignment` 'consent' | 'calendar', required: Specifies whether the period starts on the date of consent creation or lines up with a calendar. If the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days. - `half_year` object: Limit for payments made within 6 months - `maximum_amount` integer, required: A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period. `maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified. - `period_alignment` 'consent' | 'calendar', required: Specifies whether the period starts on the date of consent creation or lines up with a calendar. If the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days. - `year` object: Limit for payments made within a year - `maximum_amount` integer, required: A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period. `maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified. - `period_alignment` 'consent' | 'calendar', required: Specifies whether the period starts on the date of consent creation or lines up with a calendar. If the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days. - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) ## Response `201` Mandate Created - union - MandateCreatedAuthorizationRequired - `id` string, required: Unique ID for the mandate - `user` object, required: Details on the user of the created mandate. If you didn't pass the `user_id` in the request body when you created the mandate, an ID is generated and returned in this response. - `id` string, required: ID of the user - `status` 'authorization_required', required - `resource_token` string, required: Token to use with `/mandate` endpoints. It can be safely shared with a front end channel. - MandateCreatedAuthorizing - `id` string, required: Unique ID for the mandate - `user` object, required: Details on the user of the created mandate. If you didn't pass the `user_id` in the request body when you created the mandate, an ID is generated and returned in this response. - `id` string, required: ID of the user - `status` 'authorizing', required ## Other responses - `400`: Invalid Parameters - `401`: Unauthenticated - `403`: Forbidden - `409`: Idempotency-Key Concurrency Conflict - `422`: Idempotency-Key Reuse - `429`: Rate Limit Exceeded - `500`: Unknown Error --- [API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)