Skip to main content

Create New Virtual Card

POST 
/api/v1/cards/card/add

This endpoint creates a new virtual card. When 'is_autolimit' is set to 'TRUE', the transaction limit is automatically set to the card's current balance after each top-up. If 'is_autolimit' is 'FALSE', you must manually set 'limit_per_transaction' to a positive value not exceeding the card balance.

Request​

Body

required
    user_email emailrequired

    Email address of the card's user.

    bin Bin

    Default value: 472593

    The BIN of the card. Defaults to VISA 472593

    card_nick_name Card Nick Name

    A personalized nickname for the card.

    limit_all_time Limit All Time

    Default value: 25

    The cumulative spending limit for the card's entire lifetime.

    limit_per_transaction Limit Per Transaction

    The maximum amount allowed per transaction. Cannot exceed the overall spending limit (limit_all_time).

    is_autolimit Is Autolimit

    Default value: true

    Whether the per-transaction limit is set automatically to match the current card balance after each top-up.

    api_users_chain string[]

    An alias for the integrated client, representing a list of identifiers for API users associated with this card

    external_user_id External User Id

    The identifier for the card user within an external system, specifically referring to end-users from the api_users_chain.

Responses​

Successful Response

Schema
    cardholder_id object
    anyOf

    string

    form_factor CardFormFactorrequired

    Possible values: [physical, virtual]

    An enumeration.

    card_id object required
    anyOf

    string

    created_at Created Atrequired
    closed_at Closed At
    mask_number Mask Numberrequired
    nick_name Nick Name
    status Status
    brand Brandrequired
    settings object
    active_from Active From

    The starting datetime from which card transactions will be authorized. Transactions attempted before this time are automatically rejected.

    active_to Active To

    The ending datetime until which card transactions will be authorized. Transactions attempted after this time are automatically rejected.

    allowed_currencies Allowed Currencies

    A list of currencies in which transactions are permitted. If this field is absent, null, or an empty array, transactions in all currencies are allowed.

    allowed_transaction_count object

    An enumeration.

    limits object[]

    Transaction limits based on interval and amount. If no limits are set, will be used next values: PER_TRANSACTION - 1000 USD, DAILY - 5000 USD.

  • Array [
    • interval object

    An enumeration.

    amount Amountrequired

    The maximum amount allowed for the specified interval.

  • ]
    • bin object
    vendor Providersrequired

    Possible values: [airwallex, sunrate, wex, connex, matchmove]

    An enumeration.

    code Code

    The specific code of the BIN.

    vendor_code Vendor Code
    purpose BinPurposeEnum[]

    Possible values: [CARDS_VIRTUAL, SHARED_BALANCE_VIRTUAL_CARDS]

    issue Issue
    topup Topup
    withdrawal Withdrawal
    tariff_data object
    paymentServices PayServices[]

    Possible values: [GooglePay, ApplePay, SamsungPay]

    An optional list of payment services supported by this BIN, such as mobile payment platforms like Google Pay or Apple Pay.

    merchants string[]

    An optional list of merchant names that are specifically allowed to process payments using this BIN.

    isTokenizable Istokenizable

    Indicates if the BIN is tokenizable.

    scheme object

    An enumeration.

    address_id object

    The unique identifier of the address associated with the BIN.

    anyOf

    string

    currency_id object

    The unique identifier of the currency associated with the BIN.

    anyOf

    string

    id object required

    The unique identifier of the BIN.

    anyOf

    string

    address object
    country objectrequired
    name Namerequired
    iso_code Iso Coderequired
    city Cityrequired
    line_1 Line 1required
    line_2 Line 2required
    postal_code Postal Coderequired
    currency object
    iso_code Iso Coderequired
    digital_code Digital Coderequired
    balance object
    card_id object required

    The unique identifier of the card.

    anyOf

    string

    limit Limitrequired

    The total spending limit of the card, applicable over the card's lifetime.

    available Availablerequired

    The current available spending limit on the card. Calculated as available' = 'limit' - 'used'.

    used Usedrequired

    The total amount that has been used from the card. This is equivalent to the 'spend' amount in other endpoints.

    opening_balance Opening Balancerequired

    The balance of the card at the time of its issuance.

    topup_balance Topup Balancerequired

    The total amount added to the card through top-ups.

    limit_per_transaction Limit Per Transactionrequired

    The maximum limit allowed for a single transaction.

    pending_balance Pending Balancerequired

    The total amount in transactions that are currently pending.

    fees_balance Fees Balancerequired

    The total sum of fees charged to the card.

    incoming_balance Incoming Balancerequired

    The total amount of external payments received on the card. Currently not supported.

    withdrawal_balance Withdrawal Balancerequired

    The total amount withdrawn from the card, including limit decrease operations.

    is_autolimit Is Autolimit

    Default value: true

    is_withdrawable Is Withdrawable

    Default value: true

    is_tokenizable Is Tokenizable

    Default value: false

    user object
    email email

    The email address of the user.

    whitelabel Whitelabel

    An optional string identifier for the user's whitelabel branding.

    id object required

    The unique identifier of the user.

    anyOf

    string

    nickname Nicknamerequired

    The nickname or username of the user.

    role UserRolerequired

    Possible values: [admin, financier, teamlead, buyer]

    The role assigned to the user, defining permissions and access. Currently, 'admin' and 'buyer' roles are in use. The 'buyer' cannot directly add funds to the wallet but can request funds from an 'admin'.

    status UserStatusrequired

    Possible values: [pending, sandbox, active, deleted, on_hold]

    The current status of the user. 'pending': User registration is incomplete or awaiting confirmation. 'sandbox': User is in a testingor trial environment. 'active': User account is active and fully functional. 'deleted': User account is deleted and no longer accessible. 'on_hold': User account is temporarily suspended or on hold.

    user_type User Type

    Specifies the user type. Currently, 'cpa' is used.

    invite_accept Invite Acceptrequired

    Indicates whether the user has accepted an invitation.

    is_new_client Is New Client

    A flag that signifies whether the user registered independently or through an invite (buyer).

    account object

    Associated account information for the user, if any.

    first_name First Namerequired

    The first name of the account holder.

    middle_name Middle Name

    Default value:

    The middle name of the account holder, if any.

    last_name Last Namerequired

    The last name of the account holder.

    date_of_birth daterequired

    The date of birth of the account holder.

    phone Phonerequired

    The phone number of the account holder.

    type AccountTyperequired

    Possible values: [beneficial owner, cardholder, director, legal representative of business]

    The type of the account.

    id object required

    The unique identifier of the account.

    anyOf

    string

    user_id User Idrequired

    The unique identifier of the associated user.

    tg_account Tg Account

    The Telegram account associated with the user.

    company object

    Details of the associated company, if applicable.

    name Namerequired

    The name of the company.

    registration_number Registration Numberrequired

    The registration number of the company.

    phone Phonerequired

    The contact phone number of the company.

    primary_contact_email emailrequired

    The primary contact email address of the company.

    id object required

    The unique identifier of the company.

    anyOf

    string

Loading...