Skip to main content
POST
Register card

Authorizations

api_key
string
header
required

Path Parameters

userToken
string
required

User token.

Body

application/json

Card data (encrypted/raw) to add.

name
string
required

Card name. Example: VISA-1234.

cardtype
enum<string>
required

Card type.

Available options:
DebitCard,
CreditCard
number
string
required

Tokenized card number by VGS. Example: tok_sandbox_9PNgfqqpqwertnD1jYkdw1_1111.

nameOnCard
string
required

Card holder name. Example: John Doe.

expirationDate
string
required

Card expiration date. MMYY format. Example: 0631.

country
string
required

Country code. ISO-3166-1 alpha-2 format. Example: US for United States, MX for Mexico.

cardNetwork
enum<string>
required

Card network.

Available options:
NotApplicable,
UATP,
Visa,
ChinaUnionPay,
InterPayment,
DiscoverCard,
Dankort,
Cardguard,
MIR,
MasterCard,
Verve,
InstaPayment,
Maestro,
DinersClubInternational,
AmericanExpress,
JCB,
TROY
type
enum<string>

Payment method type.

Available options:
DebitCard,
CreditCard
isPrimary
boolean

Is primary payment method?

expirationYear
string

Card expiration year. YY format. Example: 31.

expirationMonth
string

Card expiration month. MM format. Example: 06.

securityCode
string

Tokenized CVV/CVC security code by VGS. Example: tok_sandbox_brucMoj9eTJR3xhqdmM4AQ.

currency
string

Currency code. ISO-4217 format. Example: USD.

operationId
string

Associated Operation ID (if applicable). Example: guid-1234567890.

Response

200 — OK. Card registered or existing card returned.

Scenarios for this response:

See also Full scenario matrix.

Base fields that can appear on any payment method. Discriminated variants (DebitCard, CreditCard, UBN, etc.) extend this and add required fields per type.

type
enum<string>
required

Payment method type

Type of the payment method.

Available options:
MobileWallet,
BankAccount,
DebitCard,
CreditCard,
CashLoadLocation,
AppleDigitalWallet,
GoogleDigitalWallet,
CLABE,
UBN,
VirtualNetworkAccount
canOperate
boolean

If Credit/Debit Card can operate.

paymentMethodOwner
string

VNA method owner

Example: BCP.

allowReviewAddress
boolean

If Credit/Debit Card allows review address.

allowPushDomestic
boolean

If Credit/Debit Card allows push domestic.

allowPushCrossBorder
boolean

If Credit/Debit Card allows push cross border.

allowPullDomestic
boolean

If Credit/Debit Card allows pull domestic.

allowPullCrossBorder
boolean

If Credit/Debit Card allows pull cross border.

accountPrefix
string
bin
string
paymentToken
object

The paymentToken field is only for capturing data from mobile, it won't send to numi plat

status
enum<string>
Available options:
Created,
Validated,
Blocked,
Validating,
Removed,
Disconnected,
ValidationNotApproved,
ValidatedPull,
ValidatedPush,
ValidatedPullAndPush
application
string

Application associated with the payment method.

accountId
string

Account ID associated with the payment method.

longitude
number<double>

Address longitude of the payment method.

latitude
number<double>

Address latitude of the payment method.

phoneNumber
string

Mobile phone number associated with the payment method. Must be a valid mobile phone number.

Example: +5215521206703 for MX.

country
string

Country code.

ISO 3166-1 alpha-2 format. Example: US for United States, MX for Mexico.

zipCode
string
state
string

Address state/province/department. ISO 3166-2:CC (CC: country code). Or the state short name. Example: DF for Distrito Federal, JA for Jalisco.

city
string
streetNumber
string
address3
string
address2
string
address1
string
currency
string

Currency code.

ISO 4217 format. Example: USD for United States Dollar, MXN for Mexican Peso.

externalId
string
cardNetwork
string

Credit/Debit card network

Example: Visa, MasterCard, American Express, Discover, Diners Club, JCB, UnionPay, Maestro, Mir, Verve, Troy, UATP.

cardtype
enum<string>

Credit/Debit card type

Available options:
DebitCard,
CreditCard
securityCode
string

Credit/Debit tokenized card CVV/CVC security code by VGS. Example: tok_sandbox_brucMoj9eTJR3xhqdmM4AQ.

expirationMonth
string

Credit/Debit card expiration month

expirationYear
string

Credit/Debit card expiration year

expirationDate
string

Credit/Debit card expiration date

nameOnCard
string

Credit/Debit card holder name.

number
string

If Credit/Debit, this is the tokenized card number by VGS. If UBN/VNA/CLABE, this is the number on clear text.

Example: tok_sandbox_9PNgfqqpqwertnD1jYkdw1_1111.

beneficiaryAccountId
string
tokenData
string
cardType
enum<string>
Available options:
DebitCard,
CreditCard
accountNumber
string
bankEntityNumber
string
bankName
string
bankAccountType
enum<string>
Available options:
CheckingAccount,
SavingsAccount,
OtherAccount
updatedAt
string<date-time>
createdAt
string<date-time>

Created at

isPrimary
boolean

Is primary payment method?

name
string

Payment method name

Name of the payment method. Example VISA-1234.

id
string

Payment method ID