> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token import file creation

> Create a token import file with the column definitions for cards, digital wallets, non-card tokens, bank accounts, and gift cards.

To allow for a smooth import, a template has been created that can be used for a generic token import from your current payment service to the system,

These templates: [card template](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_template.csv) [digital wallets](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_template_digital_wallet.csv) [non-card tokens](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_template_non_card.csv) [bank accounts](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_template_bank.csv) [gift cards](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_template_gift_card.csv) can be downloaded and saved as a `.csv` file. Not all fields are required for minimum import,
but sending as many fields as are available is recommended. These sample files show how a file can be populated: [card sample](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_sample.csv) [bank sample](https://raw.githubusercontent.com/gr4vy/token-import-templates/main/token_import_sample_bank.csv).

<Info>
  The import process does not modify your token file, if column data is not
  truncated the record is treated as a failure.
</Info>

### Column definitions

| Column | Restrictions | Minimum Length | Maximum Length | Definition |
| - | - | - | - | - |
| `audit_reference_id` | Required, unique | | 200 | An ID for this row that can be used for logging and audit purposes. |
| `merchant_account_id` | | | 22 | The merchant account ID that resources should be created for. This defaults to `default`. |
| `buyer.external_identifier` | Required, unique | | 200 | An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers. See [Buyer creation](./buyer-payment-creation) for more details. Must be unique. |
| `buyer.display_name` | | | 200 | A unique name for this buyer which is used in the dashboard to give a buyer a human-readable name. |
| `buyer.billing_details.email_address` | | | 320 | The email address for the buyer. |
| `buyer.billing_details.first_name` | | | 255 | The first names or given names for the buyer. |
| `buyer.billing_details.last_name` | | | 255 | The last name, or family name, of the buyer. |
| `buyer.billing_details.phone_number` | | | 320 | The phone number for the buyer should be formatted according to the [E164 number standard](https://www.twilio.com/docs/glossary/what-e164). |
| `buyer.billing_details.address.city` | | | 100 | The city for the address. |
| `buyer.billing_details.address.country` | | | 2 | The country for the address in ISO-3166 format. |
| `buyer.billing_details.address.line1` | | | 255 | The first line of the address. |
| `buyer.billing_details.address.line2` | | | 255 | The second line of the address. |
| `buyer.billing_details.address.postal_code` | | | 50 | The postal code or zip code for the address. |
| `buyer.billing_details.address.state` | | | 255 | The state, county, or province for the address. |
| `buyer.billing_details.address.state_code` | | | | The code of state, county, or province for the address in ISO 3166-2 format, for example `US-UT`. This value isn't derived from `state`, and some connectors, such as Adyen and Repay, send only `state_code` to the payment service. Include it for US and Canadian addresses. |
| `buyer.billing_details.address.house_number_or_name` | | | 255 | The house number or name for the address. Not all payment services use this field but some do. |
| `buyer.billing_details.address.organization` | | | 255 | The optional name of the company or organization to add to the address. |
| `buyer.billing_details.tax_id.kind` | | | | The kind of tax ID. See [API Docs](https://docs.gr4vy.com/reference/buyers/new-buyer) for this field's accepted values. |
| `buyer.billing_details.tax_id.value        ` | | | 50 | The tax ID for the buyer. |
| `payment_method.number` | Required (card, digital wallet) | 13 | 19 | The card number (PAN), without spaces or any other formatting. For digital wallets, this is the device primary account number (DPAN) for `applepay` and `googlepay`, or the card number for `googlepay_pan_only`. |
| `payment_method.expiration_date` | Required (card, digital wallet) | | | The credit card expiration date, formatted as a string in the `MM/YY` format. |
| `payment_method.cardholder_name` | Optional (digital wallet) | | | The cardholder name for the wallet. Defaults to the buyer's billing first and last name when omitted. |
| `payment_method.card_scheme` | Optional (digital wallet) | | | The card scheme for the wallet. Overrides the value derived from the number. Must be a valid card scheme. |
| `payment_method.card_type` | Optional (digital wallet) | | | The underlying card type for the wallet, one of `credit`, `debit`, or `prepaid`. Overrides the value derived from the number. |
| `payment_method.card_suffix` | Optional (digital wallet) | | 4 | The last four digits of the underlying card. Overrides the value derived from the number. |
| `payment_method.scheme_transaction_id` | Recommended | | 100 | The latest scheme or network transaction ID for the card or wallet. This is required to enable subsequent MIT transactions without requiring the buyer to be present. |
| `payment_method.external_identifier` | Required | | 200 | An external identifier that can be used to match the card against your own records. |
| `payment_method.token` | Required (non-card) | | | The non-card payment method's token. |
| `payment_method.token_xid` | Optional (non-card) | | | The token ID on the provider. Defaults to `payment_method.token` if not provided. |
| `payment_method.payment_service_id` | Required (non-card or gift card) | | | The `payment_service_id` for the token or `gift_card_service_id` for the gift card. |
| `payment_method.method` | Required (non-card, digital wallet) | | | The payment method's method. For digital wallets, use `applepay`, `googlepay`, or `googlepay_pan_only`. |
| `payment_method.scheme` | Required (bank) | | | The bank account's scheme, one of `ach`, `bacs`, or `sepa`. |
| `payment_method.account_number` | Required (bank) | | | The bank account number, or the IBAN when the scheme is `sepa`. An `ach` account number is at most 17 digits, a `bacs` one is 8 digits. Leading zeros are significant and must be preserved. |
| `payment_method.routing_number` | Required (`ach`, `bacs`) | | | The ABA routing number for `ach`, 9 digits, or the sort code for `bacs`, 6 digits. Optional for `sepa`, where it is the BIC. Leading zeros are significant and must be preserved. |
| `payment_method.account_type` | Optional (`ach`) | | | The type of bank account, either `checking` or `savings`. Defaults to `checking` when empty. Only used by `ach`. |
| `payment_method.account_holder.first_name` | Optional (bank) | | | The account holder's first name, for an account held by an individual. |
| `payment_method.account_holder.last_name` | Optional (bank) | | | The account holder's last name, for an account held by an individual. |
| `payment_method.account_holder.company_name` | Optional (bank) | | | The account holder's company name, for an account held by a business. |
| `payment_method.label` | Ignored for card, bank, and gift cards | | | The label to display for non-card payment methods. |
| `payment_method.last_used_at` | Ignored for gift cards | | | The timestamp in ISO-8601 format when this payment method was last used in a transaction. |
| `payment_method.cit_last_used_at` | Ignored for gift cards | | | The timestamp in ISO-8601 format when this payment method was last used in a transaction for client initiated transactions. |
| `gift_card.number` | Required (gift card) | 16 | 19 | The gift card number, without spaces or any other formatting. |
| `gift_card.pin` | Required (gift card) | 1 | | The gift card pin. |
| `gift_card.currency` | Required (gift card) | | | The gift card currency in ISO-4217 format. |
| `gift_card.expiration_date` | Required (gift card) | | | The gift card expiration date in ISO-8601 format. Leave empty if gift card doesn't expire. |

<Info>
  The import service treats a file as a digital wallet import when it includes `payment_method.number`, `payment_method.expiration_date`, and `payment_method.method`.
  The digital wallet template includes all card columns, so don't include `payment_method.method` in a card import file.
</Info>

<Info>
  The import service treats a file as a bank import when it includes `payment_method.scheme` and `payment_method.account_number`.
  These columns can't be combined with the columns of another template type in the same file.

  A bank account holder is either an individual or a company, never both. Supply either
  `payment_method.account_holder.first_name` and `payment_method.account_holder.last_name`, or
  `payment_method.account_holder.company_name`. When all three are empty the buyer's billing name is used, and
  failing that the buyer's billing address organization. A partially filled holder is used as given, so the
  fallback only applies when all three columns are empty.

  Imported bank accounts are stored with the `bank` method. You can only charge them through a connection that accepts
  stored bank account details, such as [Adyen bank account](/connections/payments/adyen-bank). Redirect connections, such
  as Adyen SEPA or Adyen ACH Direct Debit, can't charge them. See [Supported connectors](/connections/payments/bank#supported-connectors).
  Set up this connection before the first charge, otherwise the transaction fails with the error
  `There is no active payment service for this transaction.`

  An import file is expected to carry raw account numbers. Account numbers already encrypted or tokenized by another
  provider can't be imported.

  Take care when producing the file with a spreadsheet application, as these commonly treat account and routing
  numbers as numeric and silently drop their leading zeros. A routing number that arrives with too few digits is
  rejected (see the `payment_method.routing_number` column in the [Column definitions](#column-definitions)
  table above). Format both columns as text before entering any values.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.