> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment method > Enrolls a Mexican direct debit mandate and returns the `PaymentMethod` that represents the mandate. Send the mandate fields and the four consent documents under `mx_direct_debit[consent_documents]` as `multipart/form-data` in a single request. The request is atomic: if any document is invalid, Fintoc creates nothing. The mandate stays `pending` until the account holder authorizes the mandate with their bank. ## OpenAPI ````yaml reference/main-api.json POST /v2/payment_methods openapi: 3.1.0 info: title: fintoc-api version: v2026-02-01 servers: - url: https://api.fintoc.com security: [] paths: /v2/payment_methods: post: tags: - Payment methods summary: Create a payment method description: >- Enrolls a Mexican direct debit mandate and returns the `PaymentMethod` that represents the mandate. Send the mandate fields and the four consent documents under `mx_direct_debit[consent_documents]` as `multipart/form-data` in a single request. The request is atomic: if any document is invalid, Fintoc creates nothing. The mandate stays `pending` until the account holder authorizes the mandate with their bank. operationId: v2.payment-methods-create parameters: [] requestBody: content: multipart/form-data: schema: type: object properties: type: type: string enum: - mx_direct_debit description: >- Type of payment method to create. Only `mx_direct_debit` is supported. example: mx_direct_debit customer: type: string description: >- Unique identifier of the customer the payment method belongs to. example: cus_0ujsswThIGTUYm2K8FjOOfXtY1K mx_direct_debit: type: object description: Terms of the direct debit mandate. properties: account_number: type: string description: >- Account to debit. For `clabe`, the 18 digits of the standardized Mexican bank account number (CLABE). For `debit_card`, the 16 digits of the card number, which must pass the Luhn check. example: '000000000000000000' account_type: type: string enum: - clabe - debit_card description: >- Type of account that `account_number` identifies. One of `clabe` or `debit_card`. example: clabe institution_id: type: string description: >- Institution that issued the account. Required when `account_type` is `debit_card`. Ignored for `clabe`, where the first three digits of the account number identify the bank. example: mx_banco_banorte interval: type: string enum: - week - month - year description: >- How often the mandate authorizes a charge. One of `week`, `month`, or `year`. example: month max_amount: type: integer description: >- Maximum amount for each debit, in the smallest currency unit of Mexican pesos (MXN). Must be greater than `0`. The value `100000` represents `$1,000.00 MXN`. example: 100000 account_holder: type: object description: >- Identity of the person who owns the account. Each field defaults to the matching field of the customer, so you only need to send the fields that differ. properties: name: type: string description: >- Full name of the account holder. Defaults to the `name` of the customer. example: Test Customer 1 email: type: string description: >- Email address of the account holder. Defaults to the `email` of the customer. example: test.customer.1@example.com rfc: type: string description: >- Mexican tax ID (RFC) of the account holder. Defaults to the customer's `tax_id` when the customer's `tax_id_type` is `mx_rfc`. example: AAA010101AAA consent_documents: type: object description: >- The four documents that evidence the account holder's consent to the mandate. Each document must be a PDF, JPEG, or PNG, and must be between 100 bytes and 10 MB. properties: contract: type: string format: binary description: Mandate contract signed by the account holder. selfie: type: string format: binary description: >- Photograph of the account holder holding their identity document. id_front: type: string format: binary description: >- Front of the account holder's identity document, usually the Mexican voter ID card. id_back: type: string format: binary description: >- Back of the account holder's identity document, usually the Mexican voter ID card. required: - contract - selfie - id_front - id_back required: - account_number - account_type - interval - max_amount - consent_documents required: - type - customer - mx_direct_debit required: true responses: '201': description: >- The payment method Fintoc created for the mandate. Each response option below matches one payment method `type`. This endpoint only creates mandates, so it always returns the `mx_direct_debit` option, with `mx_direct_debit.status` set to `pending`. content: application/json: examples: mx_direct_debit_payment_method: value: id: pm_1zXcVbNmAsDfGhJk object: payment_method created_at: '2026-01-10T11:05:00.000Z' customer: cus_0ujsswThIGTUYm2K8FjOOfXtY1K mode: live mx_direct_debit: account_type: clabe institution_id: mx_banco_santander interval: month last_four_digits: '0000' max_amount_cents: 100000 max_amount_currency: MXN status: pending type: mx_direct_debit schema: $ref: '#/components/schemas/payment_method' '400': description: A parameter is missing or has an invalid value. content: application/json: examples: missing_document: value: error: type: invalid_request_error code: missing_parameter param: mx_direct_debit.consent_documents.id_back message: id_back is required doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' '404': description: >- The customer does not exist, belongs to another organization, or the customer's mode does not match the mode of the API key. content: application/json: examples: customer_not_found: value: error: type: invalid_request_error code: missing_resource param: customer message: 'No such customer: cus_0ujsswThIGTUYm2K8FjOOfXtY1K' doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '422': description: >- A document is outside the 100 bytes to 10 MB range or is not a PDF, JPEG, or PNG, the account number is not a valid CLABE, or the account's bank does not support direct debit. content: application/json: examples: unsupported_content_type: value: error: type: invalid_request_error code: unsupported_content_type message: >- Unsupported content type: text/csv. Allowed types: application/pdf, image/jpeg, image/png. file_too_small: value: error: type: invalid_request_error code: file_too_small message: File is smaller than the minimum size of 100 bytes. unsupported_institution: value: error: type: invalid_request_error code: unsupported_institution message: >- Direct debit is not available for the bank of this account number. schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: payment_method: description: >- A payment method represents a customer's stored payment instrument, ready to be charged without the customer going through the full authorization flow again. The shape of the object depends on its `type`. Each option below is one `type`: `bank_transfer`, `card`, `mx_direct_debit`, or `pac`. The type-specific details live under a key named after the `type`. oneOf: - $ref: '#/components/schemas/payment_method_bank_transfer' - $ref: '#/components/schemas/payment_method_card' - $ref: '#/components/schemas/payment_method_mx_direct_debit' - $ref: '#/components/schemas/payment_method_pac' discriminator: propertyName: type mapping: bank_transfer: $ref: '#/components/schemas/payment_method_bank_transfer' card: $ref: '#/components/schemas/payment_method_card' mx_direct_debit: $ref: '#/components/schemas/payment_method_mx_direct_debit' pac: $ref: '#/components/schemas/payment_method_pac' error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message payment_method_bank_transfer: type: object title: 'type: bank_transfer' description: >- Payment method backed by a linked bank account that pays through bank transfers. properties: id: type: string description: Unique identifier of the payment method. example: pm_1zXcVbNmAsDfGhJk object: const: payment_method description: Type of the object. Always `payment_method`. bank_transfer: type: - object - 'null' description: >- Details of the linked bank account that pays the transfers. `null` when the linked account backing the payment method is no longer available. properties: account_holder_id: type: string description: >- Tax identifier of the account holder, without dots or hyphens. In Chile this is the Chilean tax ID (RUT). example: '111111111' account_number: type: string description: Account number as a string, which may include leading zeros. example: '001111111111' account_type: type: string enum: - checking_account - savings_account - sight_account - rut_account - line_of_credit - credit_card description: >- Account subtype reported by the institution. One of `checking_account`, `savings_account`, `sight_account`, `rut_account`, `line_of_credit`, or `credit_card`. example: checking_account institution_id: type: string example: cl_banco_de_chile description: Identifier of the institution where the account lives. institution_name: type: string description: Human-readable name of the institution. example: Banco de Chile mfa_type: type: string description: >- Type of multi-factor authentication the institution requires to authorize a transfer, for example `sms`. An empty string when the institution does not require multi-factor authentication. example: sms status: type: string enum: - active - inactive description: >- Validity of the bank credentials backing the payment method. One of `active` or `inactive`. An `inactive` payment method cannot be charged until the customer links their account again. example: active required: - account_holder_id - account_number - account_type - institution_id - institution_name - mfa_type - status created_at: type: string format: date-time description: ISO 8601 timestamp of when the payment method was created. example: '2026-01-15T14:30:00.000Z' customer: type: string description: Unique identifier of the customer the payment method belongs to. example: cus_oVgVqlnK0PdmGirH mode: type: string enum: - live - test description: >- Mode of the payment method. `live` payment methods charge real money; `test` payment methods use fake data for integration testing. example: live type: const: bank_transfer description: Type of the payment method. Always `bank_transfer`. required: - id - object - bank_transfer - created_at - customer - mode - type payment_method_card: type: object title: 'type: card' description: Payment method backed by a stored card. properties: id: type: string description: Unique identifier of the payment method. example: pm_1zXcVbNmAsDfGhJk object: const: payment_method description: Type of the object. Always `payment_method`. card: type: - object - 'null' description: >- Details of the stored card. `null` when the card backing the payment method is no longer available. properties: active: type: boolean description: >- Whether the card can currently be charged. Fintoc automatically deactivates expired cards. example: true brand: type: string description: Brand of the card, for example `visa` or `mastercard`. example: visa country: type: string description: >- Display name of the country where the card was issued, in English. example: Chile expiration: type: object description: >- Expiration date of the card. For cards enrolled through a wallet (for example, Apple Pay), month and year are `null` because the wallet does not expose an expiration date. properties: month: type: - string - 'null' description: Two-digit expiration month. `null` for wallet cards. example: '12' year: type: - string - 'null' description: Four-digit expiration year. `null` for wallet cards. example: '2030' required: - month - year kind: type: string description: Kind of card, for example `credit` or `debit`. example: credit last_four_digits: type: string description: Last four digits of the card number. example: '4242' wallet: type: - string - 'null' enum: - apple_pay - google_pay - null description: >- Wallet used to enroll the card. Possible values are `apple_pay` and `google_pay`. `null` for cards entered manually. example: apple_pay required: - active - brand - country - expiration - kind - last_four_digits - wallet created_at: type: string format: date-time description: ISO 8601 timestamp of when the payment method was created. example: '2026-01-15T14:30:00.000Z' customer: type: string description: Unique identifier of the customer the payment method belongs to. example: cus_oVgVqlnK0PdmGirH mode: type: string enum: - live - test description: >- Mode of the payment method. `live` payment methods charge real money; `test` payment methods use fake data for integration testing. example: live type: const: card description: Type of the payment method. Always `card`. required: - id - object - card - created_at - customer - mode - type payment_method_mx_direct_debit: type: object title: 'type: mx_direct_debit' description: >- Payment method backed by a Mexican direct debit mandate that charges the customer's bank account. properties: id: type: string description: Unique identifier of the payment method. example: pm_1zXcVbNmAsDfGhJk object: const: payment_method description: Type of the object. Always `payment_method`. created_at: type: string format: date-time description: ISO 8601 timestamp of when the payment method was created. example: '2026-01-15T14:30:00.000Z' customer: type: string description: Unique identifier of the customer the payment method belongs to. example: cus_oVgVqlnK0PdmGirH mode: type: string enum: - live - test description: >- Mode of the payment method. `live` payment methods charge real money; `test` payment methods use fake data for integration testing. example: live mx_direct_debit: type: - object - 'null' description: >- Details of the direct debit mandate that charges the customer's account. `null` when the mandate backing the payment method is no longer available. properties: account_type: type: string enum: - clabe - debit_card description: >- Kind of account the mandate debits. One of `clabe` (an 18-digit CLABE, the standardized Mexican bank account number) or `debit_card`. example: clabe institution_id: type: string description: Identifier of the institution where the debited account lives. example: mx_banco_bbva interval: type: string enum: - week - month - year description: >- Frequency at which the mandate authorizes charges. One of `week`, `month`, or `year`. example: month last_four_digits: type: string description: Last four digits of the debited account. example: '1234' max_amount_cents: type: integer description: >- Maximum amount the mandate authorizes per charge, in the smallest currency unit. For example, `500000` for `$5,000.00 MXN`. example: 500000 max_amount_currency: type: string description: >- Uppercase three-letter ISO 4217 currency code of the maximum amount. example: MXN status: type: string enum: - pending - active - rejected - canceled description: >- Status of the mandate. One of `pending` (the bank has not confirmed the mandate yet), `active` (the mandate accepts charges), `rejected` (the mandate was refused and never became chargeable), or `canceled` (the mandate no longer accepts charges). Only payment methods whose mandate is `active` can be charged. example: active required: - account_type - institution_id - interval - last_four_digits - max_amount_cents - max_amount_currency - status type: const: mx_direct_debit description: Type of the payment method. Always `mx_direct_debit`. required: - id - object - created_at - customer - mode - mx_direct_debit - type payment_method_pac: type: object title: 'type: pac' description: >- Payment method backed by a direct debit (PAC) subscription that charges the customer's bank account. properties: id: type: string description: Unique identifier of the payment method. example: pm_1zXcVbNmAsDfGhJk object: const: payment_method description: Type of the object. Always `payment_method`. created_at: type: string format: date-time description: ISO 8601 timestamp of when the payment method was created. example: '2026-01-15T14:30:00.000Z' customer: type: string description: Unique identifier of the customer the payment method belongs to. example: cus_oVgVqlnK0PdmGirH mode: type: string enum: - live - test description: >- Mode of the payment method. `live` payment methods charge real money; `test` payment methods use fake data for integration testing. example: live pac: type: - object - 'null' description: >- Details of the direct debit subscription that charges the customer's account. `null` when the subscription backing the payment method is no longer available. properties: account_holder_id: type: string description: >- Tax identifier of the account holder, without dots or hyphens. In Chile this is the Chilean tax ID (RUT). example: '111111111' account_number: type: string description: >- Account number of the debited account as a string, which may include leading zeros. example: '001111111111' account_type: type: string enum: - checking_account - savings_account - sight_account - rut_account - line_of_credit - credit_card description: >- Account subtype reported by the institution. One of `checking_account`, `savings_account`, `sight_account`, `rut_account`, `line_of_credit`, or `credit_card`. example: checking_account institution: type: object description: Institution where the debited account lives. properties: id: type: string description: Identifier of the institution. example: cl_banco_de_chile country: type: string description: >- Lowercase ISO 3166-1 alpha-2 code of the institution's country. example: cl name: type: string description: Human-readable name of the institution. example: Banco de Chile required: - id - country - name status: type: string enum: - pending - active - canceled description: >- Status of the direct debit subscription. One of `pending` (the bank has not confirmed the subscription yet), `active` (the subscription accepts charges), or `canceled` (the subscription no longer accepts charges). Only payment methods whose subscription is `active` can be charged. example: active required: - account_holder_id - account_number - account_type - institution - status type: const: pac description: Type of the payment method. Always `pac`. required: - id - object - created_at - customer - mode - pac - type securitySchemes: api_key: type: apiKey name: Authorization in: header ````