---
title: "Enroll Payment Method"
method: POST
path: "/customers/{customer_id}/payment-methods"
---

# Enroll Payment Method

`POST /customers/{customer_id}/payment-methods`

## Path parameters

- `customer_id` string, required

## Request body

- object
  - `account_id` string, required — The unique identifier of the account. You find this information on [Yuno's Dashboard](https://dashboard.y.uno/) (MAX 64; MIN 36).
  - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY' | '', required — The transaction's country code (MAX 2; MIN 2; [ISO 3166-1](/reference/country-reference)).
  - `type` 'CARD' | 'ACH_ENROLLMENT' | 'NU_PAY_ENROLLMENT', required — The payment method type (MAX 255; MIN 3; [Payment type](/reference/payment-type-list)).
  - `workflow` 'DIRECT' — The payment workflow indicates whether the integration will use Yuno's SDK or will be a back to back connection. Since you are in the Direct workflow, the value must be `DIRECT`.
  - `callback_url` string — URL to return the customer after an enrollment in a provider´s environment. Only necessary for alternative payment methods integrations (MAX 255; MIN 3).
  - `token` string, uuid — Pre-generated token used to reference the payment method being enrolled.
  - `parent_type` string — Type of the parent payment method, used when enrolling a tokenized/derived method (e.g. `CARD`).
  - `account_updater` boolean — Per-card control for Card Account Updater. When set to `false`, this card is excluded from Card Account Updater and will not receive automatic card-detail updates. When omitted, the card follows your account's Account Updater configuration. Applies at enrollment.
  - `card_data` object — Specifies the details of the card. Only for `DIRECT` workflow integration.
    - `number` string, required — Card’s number without any separators (MAX 19; MIN 8) - only available for PCI certified merchants.
    - `expiration_month` integer, required — Card’s expiration month - MM (MAX 2; MIN 2) - only available for PCI certified merchants.
    - `expiration_year` integer, required — Card’s expiration year - YYYY (MAX 4; MIN 4) - only available for PCI certified merchants.
    - `security_code` string — Card’s security code (MAX 4; MIN 3) - only available for PCI certified merchants.
    - `holder_name` string — Cardholder’s full name as it appears on the card (MAX 26; MIN 3) - only available for PCI certified merchants.
    - `brand` string — Card brand (e.g. `VISA`, `MASTERCARD`, `AMEX`).
    - `scheme` string — Card scheme used to process the transaction (validated card scheme).
    - `soft_descriptor` string — Statement descriptor shown on the cardholder’s bank statement.
    - `card_pin` string — Card PIN, for payment methods that require it.
    - `authentication_method` 'FIDO2' | 'OWN_CREDENTIALS' | 'FEDERATED_ID' — Authentication method for Click-to-Pay.
  - `customer_payer` object — Information about the customer/payer associated with the payment method.
    - `code` string — Yuno customer identifier (customer code). MIN 3 / MAX 255.
    - `organization_customer_external_id` string — Customer identifier in the merchant’s own system, scoped to the organization. MIN 3 / MAX 255.
    - `email` string — Email address of the customer.
    - `ip_address` string — IP address of the customer at the time of enrollment. Required by the provider for the online ACH mandate.
    - `browser_info` object — Browser metadata. Required by the provider for the online ACH mandate.
      - `user_agent` string — Full user-agent string of the customer’s browser.
  - `payment_method` object — Payment method wrapper used for non-card methods (e.g. bank transfer / ACH) and vaulting options.
    - `type` string — Method type label for the enrolled instrument (e.g. `ACH_ENROLLMENT`). The enrollment type is driven by the top-level `type`; this field is informational.
    - `vault_on_success` boolean — When `true`, the payment method is vaulted (saved) after a successful enrollment.
    - `detail` object — Method-specific details for the instrument being enrolled.
      - `bank_transfer` object
        - `account_type` 'CHECKINGS' | 'SAVINGS' — Bank account type.
        - `account_holder_type` 'INDIVIDUAL' | 'ENTITY' — Type of account holder (e.g. `INDIVIDUAL`, `ENTITY`). Accepted and stored, but not forwarded to the provider for ACH — does not control individual vs. company treatment for ACH enrollment.
        - `bank_id` string — Identifier of the bank. MIN 3 / MAX 255.
        - `bank_name` string — Name of the bank. MIN 3 / MAX 255.
        - `bank_account` string — Bank account number. MIN 3 / MAX 255.
        - `beneficiary_name` string, required — Name of the account beneficiary. MIN 3 / MAX 255.
        - `branch` string — Bank branch code. MIN 1 / MAX 8.
        - `branch_digit` string — Branch verification digit. MIN 1 / MAX 2.
        - `routing_number` string, required — Bank routing number. MIN 3 / MAX 255.
        - `code` string — Bank code. MIN 1 / MAX 8.
        - `reference` string — Reference associated with the bank account. MIN 1 / MAX 255.
        - `bank_account_mask_number` string — Masked bank account number associated with the bank transfer (for example, ****6789). This is account data, not mandate data.
        - `mandate` object — Direct debit mandate details, for bank transfer methods that operate with mandates (for example, ACH, SEPA, BACS, PAD).
          - `id` string — Mandate identifier, as provided by the payment provider.
          - `info` string — Free-text mandate information.
          - `received_status` string — Provider status indicating whether the mandate was received. Forwarded as provided by the payment provider.
          - `existing_status` string — Provider status of the existing mandate. Forwarded as provided by the payment provider.
          - `created_at` string, date-time — Date and time when the mandate was created (ISO 8601).
          - `updated_at` string, date-time — Date and time when the mandate was last updated (ISO 8601).
  - `provider_data` object — Provider data used for token migration or provider-token enrollment. Send this object when `token_source` is `PROVIDER_API`, `MIGRATION_FILE`, or `PROVIDER_TOKEN`. Usage must be agreed with your commercial advisor in Yuno.
    - `id` string, required — The unique identifier of the payment provider.
    - `token_source` 'PROVIDER_API' | 'MIGRATION_FILE' | 'PROVIDER_TOKEN' — Origin of the provided token. Note: `PROVIDER_TOKEN` is only supported when the top-level `type` is `CARD`. Using it with `ACH_ENROLLMENT` returns an error.
    - `payment_method_token` string — Provider’s payment method token. Required when `token_source` is `PROVIDER_TOKEN`.
    - `connection_id` string, uuid — Identifier of the provider connection. Required when `token_source` is `PROVIDER_API` or `PROVIDER_TOKEN`.
  - `verify` object — Indicates whether to verify the payment with a verify transaction or not. You’ll need to have a provider defined in your CARD route. False by default.
    - `vault_on_success` boolean, required — Indicates whether to verify the payment with a verify transaction or not. You’ll need to have a provider defined in your CARD route. False by default.
    - `currency` string — Currency of the card verification. For a full list of currency codes, see [Country reference](/reference/country-reference) (MAX 3; MIN 3; ISO 4217).
    - `metadata` object[] — Optional custom key–value tags for the verification (e.g., order_ref, invoice). They are attached to the internal verify payment created by the verification — available downstream exactly like payment `metadata` (payment data, provider gateway request, routing) — and stored with the enrolled payment method's verification settings. Up to 120 items.
      - `key` string, required — The metadata key (MAX 48. Value: MIN:1, MAX:48). **[Case Sensitive]**
      - `value` string, required — The metadata key value (MAX 512. Value: MIN:1, MAX:512). **[Case Sensitive]**
  - `recurring_payment` object — Recurring / subscription billing metadata associated with the enrolled method.
    - `regular_billing` object
      - `label` string — Display label for the recurring billing plan.
      - `amount` object
        - `currency` string — Billing currency, ISO 4217 format (3 letters).
        - `value` number — Billing amount per interval. Range 0 – 9999999999.
      - `interval_unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — Billing interval unit.
      - `interval_count` integer — Number of interval units between charges (e.g. `1` = every month when `interval_unit` is `MONTH`).

## Response `201`

201

- union
  - object
    - `idempotency_key` string
    - `name` string
    - `description` string
    - `type` string
    - `category` string
    - `country` string
    - `status` string
    - `sub_status` unknown
    - `vaulted_token` string
    - `callback_url` string
    - `action` unknown
    - `redirect_url` string
    - `parent_type` string
    - `created_at` string
    - `updated_at` string
    - `card_data` object
      - `iin` string
      - `lfd` string
      - `holder_name` string — Cardholder's full name as returned by the payment provider.
      - `expiration_month` integer
      - `expiration_year` integer
      - `number_length` integer
      - `security_code_length` integer
      - `brand` string
      - `issuer` string
      - `issuer_code` unknown
      - `country_code` string — ISO 3166-1 alpha-2 country code of the card's issuing country.
      - `category` string
      - `type` string
      - `fingerprint` string
    - `last_successfully_used` unknown
    - `last_successfully_used_at` unknown
    - `preferred` unknown
    - `verify` object
      - `vault_on_success` boolean
      - `payment` unknown
  - object
    - `idempotency_key` string
    - `name` string
    - `description` string
    - `type` string
    - `category` string
    - `country` string
    - `status` string
    - `sub_status` unknown
    - `vaulted_token` string
    - `callback_url` unknown
    - `action` unknown
    - `created_at` string
    - `updated_at` string
    - `card_data` object
      - `iin` string
      - `lfd` string
      - `holder_name` string — Cardholder's full name as returned by the payment provider.
      - `expiration_month` integer
      - `expiration_year` integer
      - `number_length` integer
      - `security_code_length` integer
      - `brand` string
      - `issuer` string
      - `issuer_code` unknown
      - `country_code` string — ISO 3166-1 alpha-2 country code of the card's issuing country.
      - `category` string
      - `type` string
      - `fingerprint` string
    - `last_successfully_used` unknown
    - `last_successfully_used_at` unknown
    - `preferred` unknown
    - `verify` object
      - `vault_on_success` boolean
      - `currency` string
      - `payment` object
        - `id` string
        - `account_id` string
        - `description` string
        - `country` string
        - `status` string
        - `sub_status` string
        - `merchant_order_id` string
        - `created_at` string
        - `updated_at` string
        - `amount` object
          - `currency` string
          - `value` integer
          - `refunded` integer
          - `captured` integer
        - `transactions` object[]
          - `id` string
          - `type` string
          - `status` string
          - `response_code` string
          - `response_message` string
          - `category` string
          - `merchant_reference` string
          - `provider_data` object
            - `id` string
            - `transaction_id` string
            - `account_id` string
            - `status` string
            - `sub_status` string
            - `status_detail` string
            - `response_message` string
            - `raw_response` object
              - …
            - `third_party_transaction_id` unknown
          - `created_at` string
          - `updated_at` string
        - `metadata` object[] — The custom key–value tags sent in `verify.metadata`, echoed from the internal verify payment.
          - `key` string
          - `value` string

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403

---

[API](https://skmtc.net/y/apis/ai-caller.md) · [All operations](https://skmtc.net/y/apis/ai-caller/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/y/ai-caller/versions/05b629819b49/schema)