--- title: "Create an instrument" method: POST path: "/payment/instruments" tags: ["Instruments"] --- # Create an instrument `POST /payment/instruments` Create a payment instrument. ## Headers - `x-idempotency-key` string, uuid, required ## Request body - object - `holderId` string, uuid — Unique identifier of the Holder in Payrails. At least one of `holderId` or `holderReference` values have to be provided in the request. - `holderReference` string — Merchant-provided reference for the transaction counterparty, i.e. the paying consumer. At least one of `holderReference` or `holderId` values have to be provided in the request. - `paymentMethod` 'googlePay' | 'applePay' | 'card' | 'payPal' | 'bankAccount', required — Represents the payment method type. - `futureUsage` 'Subscription' | 'CardOnFile' | 'UnscheduledCardOnFile' — Represents the future usage to define the payment flows that the stored instrument will be used for. - `description` string — Human-friendly description of the Instrument. - `merchantReference` string — Merchant-provided reference for the instrument. - `networkTransactionReference` string — Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID. - `storeInstrument` boolean — True if the holder wants to store the instrument for future use when payment is completed. - `default` boolean, nullable — True if the holder wants to make this instrument as default. - `workspaceId` string, uuid — Workspace identifier. When a merchant has multiple network token provider configs, this determines which workspace-scoped config is used for network token provisioning. - `provisionNetworkToken` boolean — True if the merchant wants to provision a network token for this instrument. - `data` union — Type-specific information about the instrument. - object — Data specific to a Card instrument. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard', required — Network of the instrument. - `preferredScheme` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `bin` string, required — First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number). - `binLookup` object — Information about an issuer by the given BIN (or IIN). - `bin` string, required — First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number). - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `localNetwork` 'bancontact' | 'cartesbancaires' | 'dankort' | 'mada' — Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. - `issuer` string — Name of the bank or institution that issued the card. - `issuerCountry` object — Country of the bank or institution that issued the card. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `segment` string — Segment of the card, e.g. gold, black, business. - `type` string — Type of the card, e.g. credit, debit, prepaid, gift. - `typeDetails` string — More information about the card type, e.g. personal, commercial. - `isNetworkToken` boolean — Indicates whether the card credential represents a network token rather than a primary account number (PAN). - `isFlexCard` boolean — Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. - `billingAddress` object — Billing Address of the instrument. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `suffix` string, required — Last digits of the Card number. - `expiryMonth` string — Expiry month of the Card. - `expiryYear` string — Expiry year of the Card. - `holderName` string — Name of the owner of the Card. - object — Encrypted card details. - `encryptedData` string, required — Encrypted sensitive payment details for the instrument tokenization. The instrument details should be encrypted with the RSA public key provided by Payrails SDK using JWE with encryption algorithm RSA-OAEP-256 and content encryption A256CBC-HS512. - `encryptedDataType` 'card' | 'networkToken', nullable — Type of token provided in the encyrptedData. e.g. 'card' when tokenizing fpan, 'network token' when tokenizing dpan or network token. - `billingAddress` object — Information about a physical address. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `eci` string — The code indicating the result of the attempt to authenticate the cardholder. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `displayName` string — Instrument name suitable for display. - `vaultProviderConfigId` string, uuid, nullable — Vault provider configuration ID of the vault that the encryptedData is meant for. - object — Data specific to a BankAccount instrument. - `holder` object — The data structure for a holder's personal information. - `firstName` string — The first name of the account holder. - `lastName` string — The last name of the account holder. - `companyName` string — The company name for business holders. - `address` object — The address of the account holder. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `email` string, email — The email address of the account holder. - `dob` string, date — The date of birth of the account holder (YYYY-MM-DD). - `country` object — The country of the account holder. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `city` string — The city of the account holder. - `type` 'individual' | 'corporate' — The type of account holder. - `bank` object — The data structure for a bank's information. - `name` string — The name of the bank. - `branchCode` string — The branch code of the bank. - `code` string — The bank code. - `address` object — The address of the bank. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `swiftCode` string — The SWIFT/BIC code of the bank. - `account` object — The data structure for an account's information. - `number` string — The bank account number. - `iban` string — The International Bank Account Number (IBAN). - `currency` string — ISO 3-letter currency code. - `country` object — The country of the account. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `type` 'savings' | 'current' — The type of bank account. - object — Data specific to a PayPal instrument. - `email` string — Email of the PayPal account. - `payerId` string — ID of the PayPal payer account. - `billingAddress` object — Billing Address of the instrument. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - object — Data specific to a DCB instrument. - `msisdn` string — Mobile number of the holder MSISDN Stands for Mobile Station International Subscriber Directory Number. - `msisdnTail` string — Last 4 digits of the mobile number of the holder. - `country` object — Country of the holder. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `carrierNetwork` string — Carrier network of the msisdn. - object — Payment token data obtained from Apple or Google. - `paymentToken` string, required — Encrypted payment token object obtained on merchant's client-side with ApplePay/GooglePay SDK, and needed for creating an instrument on Payrails Vault. - object — Payment token data obtained from Apple or Google. - `paymentToken` string, required — Encrypted payment token object obtained on merchant's client-side with ApplePay/GooglePay SDK, and needed for creating an instrument on Payrails Vault. - `token` object, nullable — Token-specific information about the instrument. Required when creating an instrument from a tokenization tool like the Payrails SDK. - `providerId` string, uuid, required — Provider of the instrument token. - `providerConfigId` string, uuid, required — Provider config of the instrument token. - `reference` string, required — Id of the instrument token on the provider. - `type` 'network' | 'vault' | 'psp' | 'networkOffers' | 'networkGateway' — Type of the token. - `requestNetworkToken` boolean — Flag indicating if the network token should be requested in the provider. - `meta` object — Any merchant or provider-specific data that should be stored for context in the token. - `encryptedDataAttributes` object — Additional attributes for the instrument tokenization. - `tokenMigrationId` string — Token migration ID for the instrument tokenization in case the instrument is tokenized as part of a token migration. - `tokenMigrationRunId` string, uuid — Token migration run ID for the instrument tokenization in case the instrument is tokenized as part of a token migration. - `tokenMigrationReference` string — Token migration reference for the instrument tokenization in case the instrument is tokenized as part of a token migration. ## Response `201` Created. - object - `id` string, uuid, required — Id of the instrument. - `createdAt` string, date-time, required — Date and time when the Instrument was created in Payrails. - `updatedAt` string, date-time, required — When the Instrument was last updated. - `holderId` string, uuid, required — Unique identifier of the Holder in Payrails. - `paymentMethod` 'alexBankMa7fazty' | 'applePay' | 'audi2pay' | 'bankAccount' | 'card' | 'cibSmartWallet' | 'easypaisa' | 'etisalatCash' | 'fawryMobileWallet' | 'fawryPay' | 'googlePay' | 'jazzCash' | 'nbePhoneCash' | 'orangeCash' | 'payPal' | 'qnbEWallet' | 'weCash' | 'genericRedirect' | 'alfa' | 'konnect' | 'eftPro' | 'netBanking' | 'upi' | 'cashFreeWallet' | 'paytmWallet' | 'phonePe', required — Represents the payment method type. - `status` 'created' | 'deleted' | 'enabled' | 'disabled' | 'transient', required — Status of the instrument. - `displayName` string — Instrument name suitable for display. - `description` string — Description of the instrument. - `default` boolean, nullable — True if this instrument is set as default for the holder. - `merchantReference` string — Merchant-provided reference for the instrument. - `fingerprint` string — System-wide unique identifier of the Instrument. If two Holders have the same instrument stored, this value will be the same for both, but the instrument and token IDs will be different. Cannot be used for payments, should only be used for analytics and fraud prevention. - `futureUsage` 'Subscription' | 'CardOnFile' | 'UnscheduledCardOnFile' — Represents the future usage to define the payment flows that the stored instrument will be used for. - `networkTransactionReference` string — Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID. - `data` union — Type-specific information about the instrument. - object — Data specific to a Card instrument. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard', required — Network of the instrument. - `preferredScheme` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `bin` string, required — First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number). - `binLookup` object — Information about an issuer by the given BIN (or IIN). - `bin` string, required — First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number). - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `localNetwork` 'bancontact' | 'cartesbancaires' | 'dankort' | 'mada' — Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. - `issuer` string — Name of the bank or institution that issued the card. - `issuerCountry` object — Country of the bank or institution that issued the card. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `segment` string — Segment of the card, e.g. gold, black, business. - `type` string — Type of the card, e.g. credit, debit, prepaid, gift. - `typeDetails` string — More information about the card type, e.g. personal, commercial. - `isNetworkToken` boolean — Indicates whether the card credential represents a network token rather than a primary account number (PAN). - `isFlexCard` boolean — Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. - `billingAddress` object — Billing Address of the instrument. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `suffix` string, required — Last digits of the Card number. - `expiryMonth` string — Expiry month of the Card. - `expiryYear` string — Expiry year of the Card. - `holderName` string — Name of the owner of the Card. - object — Data specific to a BankAccount instrument. - `holder` object — The data structure for a holder's personal information. - `firstName` string — The first name of the account holder. - `lastName` string — The last name of the account holder. - `companyName` string — The company name for business holders. - `address` object — The address of the account holder. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `email` string, email — The email address of the account holder. - `dob` string, date — The date of birth of the account holder (YYYY-MM-DD). - `country` object — The country of the account holder. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `city` string — The city of the account holder. - `type` 'individual' | 'corporate' — The type of account holder. - `bank` object — The data structure for a bank's information. - `name` string — The name of the bank. - `branchCode` string — The branch code of the bank. - `code` string — The bank code. - `address` object — The address of the bank. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `swiftCode` string — The SWIFT/BIC code of the bank. - `account` object — The data structure for an account's information. - `number` string — The bank account number. - `iban` string — The International Bank Account Number (IBAN). - `currency` string — ISO 3-letter currency code. - `country` object — The country of the account. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `type` 'savings' | 'current' — The type of bank account. - object — Data specific to a PayPal instrument. - `email` string — Email of the PayPal account. - `payerId` string — ID of the PayPal payer account. - `billingAddress` object — Billing Address of the instrument. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - object — Data specific to a GooglePay instrument. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard', required — Network of the instrument. - `networkDisplayName` string — Display-friendly name of the network. - `binLookup` object — Information about an issuer. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `localNetwork` 'bancontact' | 'cartesbancaires' | 'dankort' | 'mada' — Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. - `issuer` string — Name of the bank or institution that issued the card. - `issuerCountry` object — Country of the bank or institution that issued the card. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `segment` string — Segment of the card, e.g. gold, black, business. - `type` string — Type of the card, e.g. credit, debit, prepaid, gift. - `typeDetails` string — More information about the card type, e.g. personal, commercial. - `isNetworkToken` boolean — Indicates whether the card credential represents a network token rather than a primary account number (PAN). - `isFlexCard` boolean — Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. - `billingAddress` object — Billing Address of the instrument. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `suffix` string, required — Last digits of the Card number. - `expiryMonth` string — Expiry month of the Card. - `expiryYear` string — Expiry year of the Card. - `paymentToken` string — One-time payment token sent by client-side for execution of payment on backend. - `eci` string — Payment System-specific value provided by the ACS to indicate the results of the attempt to authenticate the Cardholder. - `cardHolderAuthenticated` boolean — Indicates that identification and verifications (ID&V) was performed on the returned payment credential. - `googleMessageId` string — Unique identifier for the Google Pay message. - `googleMessageExpirationId` string — Expiration time for the Google Pay message. - object — Data specific to a ApplePay instrument. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard', required — Network of the instrument. - `networkDisplayName` string — Display-friendly name of the network. - `binLookup` object — Information about an issuer. - `network` 'unspecified' | 'visa' | 'visadankort' | 'mastercard' | 'amex' | 'diners' | 'discover' | 'unionpay' | 'unionpayuzcard' | 'maestro' | 'maestrobancontact' | 'hipercard' | 'jcb' | 'jcblankapay' | 'argencard' | 'aura' | 'belkart' | 'bpfuelcard' | 'cabal' | 'carnet' | 'cirrus' | 'chjonesfuelcard' | 'uzcard' | 'codensa' | 'dankort' | 'dinacard' | 'duet' | 'ebt' | 'eftpos' | 'elo' | 'euroshellfuelcard' | 'gecapital' | 'bc' | 'hrgstore' | 'humo' | 'lankapay' | 'lukoilfuelcard' | 'bancontact' | 'meeza' | 'newday' | 'mir' | 'ourocard' | 'pagobancomat' | 'paypak' | 'paypal' | 'phhfuelcard' | 'prostir' | 'rupay' | 'sbercard' | 'sodexo' | 'starrewards' | 'cencosud' | 'naranja' | 'troy' | 'uatp' | 'ukfuelcard' | 'verve' | 'voyager' | 'vpay' | 'wex' | 'cmi' | 'atm' | 'bankcard' | 'localbrand' | 'loyalty' | 'privatelabel' | 'fuelcard' | 'redfuelcard' | 'redliquidfuelcard' — Network of the instrument. - `localNetwork` 'bancontact' | 'cartesbancaires' | 'dankort' | 'mada' — Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. - `issuer` string — Name of the bank or institution that issued the card. - `issuerCountry` object — Country of the bank or institution that issued the card. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `segment` string — Segment of the card, e.g. gold, black, business. - `type` string — Type of the card, e.g. credit, debit, prepaid, gift. - `typeDetails` string — More information about the card type, e.g. personal, commercial. - `isNetworkToken` boolean — Indicates whether the card credential represents a network token rather than a primary account number (PAN). - `isFlexCard` boolean — Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. - `billingAddress` object — Billing Address of the instrument. - `street` string — The name of the street of a postal address. - `doorNumber` string — The number on the door, building, or room. - `complement` string — Additional addressing information, 2nd line of postal address. - `area` string — The name of the suburb or area within a city. - `city` string — The name of the city of a postal address. - `postalCode` string — The postal code. - `state` string — The name of the state a postal address is in. - `country` object — The country where the address is in. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `latitude` number, float — Latitude of the address in the GPS coordinate system. - `longitude` number, float — Longitude of the address in the GPS coordinate system. - `phone` object — The phone to contact in the address (can be different that the customer's). - `countryCode` string — International prefix of the phone, if known separately. - `number` string, required — The local number of the phone, such that `countryCode` + `number` can be dialed. - `alias` string — Name of the address, e.g. home, work. - `name` string — Name of the person to whom the address belongs to. - `lastName` string — Last name of the person to whom the address belongs to. - `email` string — Email of the person to whom the address belongs to. - `suffix` string, required — Last digits of the Card number. - `expiryMonth` string — Expiry month of the Card. - `expiryYear` string — Expiry year of the Card. - `paymentToken` string — One-time payment token sent by client-side for execution of payment on backend. - `eci` string — Payment System-specific value provided by the ACS to indicate the results of the attempt to authenticate the Cardholder. - `cardHolderAuthenticated` boolean — Indicates that identification and verifications (ID&V) was performed on the returned payment credential. - object — Data specific to a DCB instrument. - `msisdn` string — Mobile number of the holder MSISDN Stands for Mobile Station International Subscriber Directory Number. - `msisdnTail` string — Last 4 digits of the mobile number of the holder. - `country` object — Country of the holder. - `code` string, required — ISO 3166-1 alpha-2 country code. - `iso3` string — ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. - `name` string — The English name of the country. Returned by Payrails, but not interpreted in requests. - `carrierNetwork` string — Carrier network of the msisdn. - `tokens` object[] — List of tokens inside the instrument. Not included by default, `includeTokens` query parameter must be used. - `id` string, uuid, required — Id of the token in Payrails. - `createdAt` string, date-time, required — Date and time when the Token was created in Payrails. - `updatedAt` string, date-time, required — When the Token was last updated. - `instrumentId` string, uuid, required — Id of the payment instrument the token belongs to. - `status` 'created' | 'enabled' | 'disabled' | 'deleted', required — Status of the token. - `type` 'network' | 'vault' | 'psp' | 'networkOffers' | 'networkGateway', required — Type of the token. - `providerId` string, uuid, required — Id of the provider the token belongs to. - `providerConfigId` string, uuid — Id of the configuration in the provider the token belongs to. - `reference` string, required — Unique identifier of the token in the provider's system. - `meta` object — Any merchant or provider-specific data that should be stored for context in the token. ## Other responses - `400` — Bad Request. - `401` — Unauthorized. - `403` — Insufficient Scope. - `404` — Not Found. - `429` — Too Many Requests. --- [API](https://skmtc.net/payrails/apis/payrails-api-reference.md) · [All operations](https://skmtc.net/payrails/apis/payrails-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payrails/payrails-api-reference/revisions/9dd2f0158582/schema)