Create Card

POST CARD-US Node to Create Card

After you create a User, OAuth the user and open a deposit account or FBO account, you are ready to issue a debit card (CARD-US or SUBCARD-US). To get started, create a CARD-US or SUBCARD-US node as outlined below.

Recommended: Check out our UI for Debit Card Issuance.

API ENDPOINT

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

PATH PARAMETER

user_id:
required
string

The user ID of the user you wish to add the CARD-US node under

BODY PARAMETER

type:
required
string

Type of node you wish to add

info.nickname:
required
string

Nickname associated with the node

info.document_id:
required
string

Document ID of user's base document that the card is associated with

extra.supp_id:
string

Any ID you wish to register to the node

EXAMPLE REQUEST

POST /v3.1/users/5ba035f9f8db93006160cd3d/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_j2NVvKDfSqQGsBk3aFZ8c4L6lxXOHt0yJRnP5C90|5aae733c07d79c741fbb12e039bbee6a
Content-Type: application/json


{
  "type": "CARD-US",
  "info": {
    "nickname":"My Debit Card",
    "document_id":"2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8"
  }
}

EXAMPLE RESPONSE

{
    "error_code": "0",
    "http_code": "200",
    "limit": 20,
    "node_count": 1,
    "nodes": [
        {
            "_id": "5ba05ed620b3aa005882c52a",
            "_links": {
                "self": {
                    "href": "https://uat-api.synapsefi.com/v3.1/users/5ba035f9f8db93006160cd3d/nodes/5ba05ed620b3aa005882c52a"
                }
            },
            "allowed": "INACTIVE",
            "client": {
                "id": "5ade26b4567a900029e2afd2",
                "name": " YY Testing Acct"
            },
            "extra": {
                "note": null,
                "other": {
                    "access_token": "5ba05ed47466d8002208b517"
                },
                "supp_id": ""
            },
            "info": {
                "balance": {
                    "amount": 0,
                    "currency": "USD"
                },
                "card_hash": "e82d9c5bde8e1fbbdba4a298ee905131fd36e3d803d0e3b235902bf18b079c1c",
                "card_number": "3082",
                "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8",
                "monthly_withdrawals_remaining": null,
                "name_on_account": " ",
                "nickname": "My Debit Card"
            },
            "is_active": true,
            "timeline": [
                {
                    "date": 1537236676466,
                    "note": "Node created."
                }
            ],
            "type": "CARD-US",
            "user_id": "5ba035f9f8db93006160cd3d"
        }
    ],
    "page_count": 1,
    "success": true
}

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.

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

VIRTUAL CARDS VS PHYSICAL CARDS

To issue a virtual card, simply create the card and remember to update the card preferences before spending. These preferences include pos_withdrawal_limit, atm_withdrawal_limit, and allow_foreign_transactions.

To ship a physical card to the user, make our Ship Debit Card API call. This will be a physical copy of your virtual card - same card number, expiration and CVV.

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

Negative Balance Reconciliation

We reconcile negative balances when accounts have been negative for 30 days with no successful activity. These reconciliations occur throughout the month, and funds will be debited from your reserve account to reconcile these balances. After an account has been reconciled, the user will be locked. If the user is locked, but they still wish to repay their negative balance, please send us the User ID to unlock the user.

For example:
If a user has a negative balance of -$500 and they pay +$400 toward that negative balance before the 30 day period is up, we will reset the 30 day countdown. If another 30 days passes and there is no successful activity, we will reconcile the remaining negative balance of -$100 from your reserve funds.

We recommend setting up webhooks to monitor your reserve account balance. This will help you automatically fund your reserve when it falls below your required minimum balance.

Subscribe to Webhooks

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