Issue a Card Number

Create a debit card for a Synapse native account

Currently in Beta

Card number issuance is currently in beta (Sandbox only).

After you create a User, OAuth the user and open a deposit account or FBO account, you are ready to issue a debit card. Issuing a card number allows you to easily enable debit card capability to an already existing deposit or subaccount.

This feature allows you to issue multiple card numbers to a single deposit or sub-account. This can be used to generate card numbers for specific services (internet, bills, etc.) or a pooled account with multiple cards attached.

Note: Card numbers can only be issued for DEPOSIT-US, SUBACCOUNT-US and LOAN-US accounts that have been created with a base document id supplied. Please refer to opening deposit accounts to learn more. If you previously opened an account without supplying a document_id you will have to create a new account with the document_id supplied.

API ENDPOINT

https://uat-api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets

PATH PARAMETER

user_id :
required
string

ID of user who owns node

node_id :
required
string

ID of node you'd like to add the card number for

BODY PARAMETER

nickname:
required
string

ID of user who owns node

account_class:
required
string

Type of subnet. this should be DEBIT_CARD

EXAMPLE REQUEST

POST /v3.1/users/59c9f69a89ec34002e1b4b2e/nodes/59c9f6a66d7d8a002f71b191/subnets HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_xEyuYzmPN6Rp120Kg08Ma3SdO4w5c9ZFBnWfbJer|e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
	"nickname":"My Debit Card",
	"account_class":"DEBIT_CARD"
}
node_id= "59c9f6a66d7d8a002f71b191"
body= {
	"nickname":"My Debit Card",
	"account_class":"DEBIT_CARD"
}

user.create_subnet(node_id, body)
const nodeID = '59c9f6a66d7d8a002f71b191';
const body = {
	"nickname":"My Debit Card",
	"account_class":"DEBIT_CARD"
};

user.createSubnet(nodeID, body);
node_id= "59c9f6a66d7d8a002f71b191"
body= {
	"nickname":"My Debit Card",
	"account_class":"DEBIT_CARD"
}

user.create_subnet(node_id: node_id, payload: body)
$nodeid = '59c9f6a66d7d8a002f71b191';
$body = (object)[
   "nickname" => "My Debit Card",
   "account_class" => "DEBIT_CARD"
];
$user->create_subnet($nodeid, $body);
nodeID := "59c9f6a66d7d8a002f71b191"
body := `{
  "nickname":"My Debit Card",
  "account_class":"DEBIT_CARD"
}`

data, err := user.CreateSubnet(nodeID, body)

EXAMPLE RESPONSE

{
    "_id": "59c9f77cd412960028b99d2b",
    "_links": {
        "self": {
            "href": "https://uat-api.synapsefi.com/v3.1/users/59c9f69a89ec34002e1b4b2e/nodes/59c9f6a66d7d8a002f71b191/subnets/59c9f77cd412960028b99d2b"
        }
    },
    "access_token": "5bc920f2fff373002bf0d51b",
    "account_class": "DEBIT_CARD",
    "card_hash": "78eb685b26d99d32538feb97cfd1274f994bdde48fa75471f22ba3029cbbc4e0",
    "card_number": "5431",
    "card_style_id": null,
    "client": {
        "id": "59c9f77cd412960028b99d2b",
        "name": "SynapseFI"
    },
    "cvc": "***",
    "exp": "2022-11-17",
    "nickname": "My Debit Card",
    "node_id": "59c9f6a66d7d8a002f71b191",
    "preferences": {
        "allow_foreign_transactions": false,
        "daily_atm_withdrawal_limit": 100,
        "daily_transaction_limit": 1000,
        "spending_limit": false
    },
    "status": "ACTIVE",
    "user_id": "59c9f69a89ec34002e1b4b2e"
}

After the debit card is successfully created, the card's allowed status will be set to INACTIVE and the card's timeline will be updated to reflect that the card was created (see below):

"timeline": [
        {
            "date": 1538021004393,
            "note": "Card created."
        }
    ]

You have now successfully created a virtual card. Remember to update the card preferences before spending. These preferences include pos_withdrawal_limit, atm_withdrawal_limit, and allow_foreign_transactions.

Subscribe to Webhooks

We recommend that you subscribe to webhooks to stay updated on the status of nodes.

PCI Considerations

Please DO NOT store card numbers. Please also review the following before displaying card information.

Web Interfaces:
If you plan to have a web version of your app, we do not recommend displaying card_number, cvc and exp date unless you are PCI compliant. This is because you will have to route this through your server, even if you are not storing card information. We recommend using our UI as a Service component for this use case, so you can redirect users there when viewing card details.

App Interfaces:
For applications, you can do the GET API call in the app itself. That way you are in full control of the UI without transmitting card data through your servers. Here is what we recommend:

  1. OAuth the user on your server, but with only scope "NODE|GET"
  2. Send this oauth_key to the user’s app
  3. Do full_dehydrate=yes from the app

Next Step: To print the card as a physical card, ship a physical card to the user. This will be a physical copy of your virtual card - same card number, expiration and CVV.

CARD RETURN REASONS

CR01

Transaction not approved; Possible NSF

CR02

International transaction detected; This card does not have international transaction permissions

CR03

Transaction exceeds ATM or POS withdrawal limits

CR04

Invalid PIN attempted; Please try again or reset the pin

CR05

Card status is in a state which does not allow for any transactions

CR06

Invalid expiration date

CR07

Transaction validation failed

CR08

There is an issue with the card; please check the card

CR09

There is an issue associated with the card deposit account of the card

CR10

Check returned; Possible NSF or invalid check