Token import file creation

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 digital wallets non-card tokens gift cards 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. This sample file provides an example of how this file can be populated.

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

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 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.
`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.
`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 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.label`	Ignored for card 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.

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.

Get started

Integration guides

Best Practices

Resources

Features

Other

Token import file creation

Column definitions

​Column definitions

Column definitions