Link a Card

Link a credit or debit card

After you Create a User and OAuth the user, you are ready to link a card.

We recommend using our Interchange UI to link a card, rather than building your own UI.

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 INTERCHANGE-US node under

BODY PARAMETER

type :
required
string

Type of node you wish to add (this is INTERCHANGE-US

info.nickname :
required
string

Nickname for the node. It is very important to assign a nickname to the node for INTERCHANGE-US, because you can never retrieve the card_number back from the API

info.card_number :
required
string

Encrypted card number

info.exp_date :
required
string

Encrypted expiration date of the card YYYYMM

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

extra.note :
string

Memo tagged with the node

is_active :
string

If the node is indexed or marked deleted.

EXAMPLE REQUEST

You will only need the card number and expiration date to link a card. The CVV and billing address are not needed.

POST /v3.1/users/594e0fa2838454002ea317a0/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_auVIbQ8WXC0pnLU9ivEs4tcHDejqFJlwoNrZ3fO1|e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
  "type": "INTERCHANGE-US",
  "info": {
    "nickname": "My Debit Card",
    "card_number": "Zoo8g2vBUjt7TwmEpRW8f6eQT3AOEEYePw2LkoxD+mO9lOT5OemHlGwgamgLGUbrmWu3DPwnEr2IqDy5YMFVgvQWP3w9nLOFzFFSW43auDgsVAqZScoRf8nI+6/B9KvOEV4XI8JeyXT+O+y3p3RtbiXGmYQNJ56Hy3hs2E5O+yn+3fpLfJQpVvNc38V+aE21VEsJuXFFNtS/8r4jJ6Dx/etTEaE/rtcEUEbwLLHFHjPiOWaHWZPuhXFLtyYrR9zG8FWSJVFwNTG/mEpv2O7We1iCB+9WoEKqdHyGwjjBcVgkUlU5huJIXv9xj53RGNvmHkDFTqgrlHpKkb0E/Ot0Zg==",
    "exp_date": "ctA4Zj1CP0WCiMefPYsyewVbIHNilfwA09X9NSCyWxft4WGwFZmZkhsBJh51QL751/iFkUHbd09ZpDYjS86PqyNPZ5LkBueGHDIghLwWyzH1l99RiIs8urOW9c4g3L1USD+kzzRAqG1DBkW47FAX6AhPSi3YgQd94ery1H+asaqDrP79ayzoJ+nRXeEqe83FIgNUk/J5+EcAz3JYnoBmp1sfz7a4zHkvk0eKCxQWLETdqvONyCZyXdC/4CkaCxJ/87VsN3i4+ToULtSluRv8xr1NpRhzipKiEKTYW1nvNDAaJQezTVP/+GxmTmQfnfpVNDpJbXjNrOTej1HgMFpg4w==",
    "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8"
  }
}
body = {
  "type": "INTERCHANGE-US",
  "info": {
    "nickname": "My Debit Card",
    "card_number": "Zoo8g2vBUjt7TwmEpRW8f6eQT3AOEEYePw2LkoxD+mO9lOT5OemHlGwgamgLGUbrmWu3DPwnEr2IqDy5YMFVgvQWP3w9nLOFzFFSW43auDgsVAqZScoRf8nI+6/B9KvOEV4XI8JeyXT+O+y3p3RtbiXGmYQNJ56Hy3hs2E5O+yn+3fpLfJQpVvNc38V+aE21VEsJuXFFNtS/8r4jJ6Dx/etTEaE/rtcEUEbwLLHFHjPiOWaHWZPuhXFLtyYrR9zG8FWSJVFwNTG/mEpv2O7We1iCB+9WoEKqdHyGwjjBcVgkUlU5huJIXv9xj53RGNvmHkDFTqgrlHpKkb0E/Ot0Zg==",
    "exp_date": "ctA4Zj1CP0WCiMefPYsyewVbIHNilfwA09X9NSCyWxft4WGwFZmZkhsBJh51QL751/iFkUHbd09ZpDYjS86PqyNPZ5LkBueGHDIghLwWyzH1l99RiIs8urOW9c4g3L1USD+kzzRAqG1DBkW47FAX6AhPSi3YgQd94ery1H+asaqDrP79ayzoJ+nRXeEqe83FIgNUk/J5+EcAz3JYnoBmp1sfz7a4zHkvk0eKCxQWLETdqvONyCZyXdC/4CkaCxJ/87VsN3i4+ToULtSluRv8xr1NpRhzipKiEKTYW1nvNDAaJQezTVP/+GxmTmQfnfpVNDpJbXjNrOTej1HgMFpg4w==",
    "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8"
  }
}

user.create_node(body)
const body = {
  "type": "INTERCHANGE-US",
  "info": {
    "nickname": "My Debit Card",
    "card_number": "Zoo8g2vBUjt7TwmEpRW8f6eQT3AOEEYePw2LkoxD+mO9lOT5OemHlGwgamgLGUbrmWu3DPwnEr2IqDy5YMFVgvQWP3w9nLOFzFFSW43auDgsVAqZScoRf8nI+6/B9KvOEV4XI8JeyXT+O+y3p3RtbiXGmYQNJ56Hy3hs2E5O+yn+3fpLfJQpVvNc38V+aE21VEsJuXFFNtS/8r4jJ6Dx/etTEaE/rtcEUEbwLLHFHjPiOWaHWZPuhXFLtyYrR9zG8FWSJVFwNTG/mEpv2O7We1iCB+9WoEKqdHyGwjjBcVgkUlU5huJIXv9xj53RGNvmHkDFTqgrlHpKkb0E/Ot0Zg==",
    "exp_date": "ctA4Zj1CP0WCiMefPYsyewVbIHNilfwA09X9NSCyWxft4WGwFZmZkhsBJh51QL751/iFkUHbd09ZpDYjS86PqyNPZ5LkBueGHDIghLwWyzH1l99RiIs8urOW9c4g3L1USD+kzzRAqG1DBkW47FAX6AhPSi3YgQd94ery1H+asaqDrP79ayzoJ+nRXeEqe83FIgNUk/J5+EcAz3JYnoBmp1sfz7a4zHkvk0eKCxQWLETdqvONyCZyXdC/4CkaCxJ/87VsN3i4+ToULtSluRv8xr1NpRhzipKiEKTYW1nvNDAaJQezTVP/+GxmTmQfnfpVNDpJbXjNrOTej1HgMFpg4w==",
    "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8"
  }
};

user.createNode(body);
body = {
  "type": "INTERCHANGE-US",
  "info": {
    "nickname": "My Debit Card",
    "card_number": "Zoo8g2vBUjt7TwmEpRW8f6eQT3AOEEYePw2LkoxD+mO9lOT5OemHlGwgamgLGUbrmWu3DPwnEr2IqDy5YMFVgvQWP3w9nLOFzFFSW43auDgsVAqZScoRf8nI+6/B9KvOEV4XI8JeyXT+O+y3p3RtbiXGmYQNJ56Hy3hs2E5O+yn+3fpLfJQpVvNc38V+aE21VEsJuXFFNtS/8r4jJ6Dx/etTEaE/rtcEUEbwLLHFHjPiOWaHWZPuhXFLtyYrR9zG8FWSJVFwNTG/mEpv2O7We1iCB+9WoEKqdHyGwjjBcVgkUlU5huJIXv9xj53RGNvmHkDFTqgrlHpKkb0E/Ot0Zg==",
    "exp_date": "ctA4Zj1CP0WCiMefPYsyewVbIHNilfwA09X9NSCyWxft4WGwFZmZkhsBJh51QL751/iFkUHbd09ZpDYjS86PqyNPZ5LkBueGHDIghLwWyzH1l99RiIs8urOW9c4g3L1USD+kzzRAqG1DBkW47FAX6AhPSi3YgQd94ery1H+asaqDrP79ayzoJ+nRXeEqe83FIgNUk/J5+EcAz3JYnoBmp1sfz7a4zHkvk0eKCxQWLETdqvONyCZyXdC/4CkaCxJ/87VsN3i4+ToULtSluRv8xr1NpRhzipKiEKTYW1nvNDAaJQezTVP/+GxmTmQfnfpVNDpJbXjNrOTej1HgMFpg4w==",
    "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8"
  }
}

user.create_node(payload: body)
$info= (object) [
   "nickname" => "My Debit Card",
   “card_number” => “Zoo8g2vBUjt7TwmEpRW8f6eQT3AOEEYePw2LkoxD+mO9lOT5OemHlGwgamgLGUbrmWu3DPwnEr2IqDy5YMFVgvQWP3w9nLOFzFFSW43auDgsVAqZScoRf8nI+6/B9KvOEV4XI8JeyXT+O+y3p3RtbiXGmYQNJ56Hy3hs2E5O+yn+3fpLfJQpVvNc38V+aE21VEsJuXFFNtS/8r4jJ6Dx/etTEaE/rtcEUEbwLLHFHjPiOWaHWZPuhXFLtyYrR9zG8FWSJVFwNTG/mEpv2O7We1iCB+9WoEKqdHyGwjjBcVgkUlU5huJIXv9xj53RGNvmHkDFTqgrlHpKkb0E/Ot0Zg==,
“exp_date” => "ctA4Zj1CP0WCiMefPYsyewVbIHNilfwA09X9NSCyWxft4WGwFZmZkhsBJh51QL751/iFkUHbd09ZpDYjS86PqyNPZ5LkBueGHDIghLwWyzH1l99RiIs8urOW9c4g3L1USD+kzzRAqG1DBkW47FAX6AhPSi3YgQd94ery1H+asaqDrP79ayzoJ+nRXeEqe83FIgNUk/J5+EcAz3JYnoBmp1sfz7a4zHkvk0eKCxQWLETdqvONyCZyXdC/4CkaCxJ/87VsN3i4+ToULtSluRv8xr1NpRhzipKiEKTYW1nvNDAaJQezTVP/+GxmTmQfnfpVNDpJbXjNrOTej1HgMFpg4w=="
];
$body = (object) [
   'type' => 'INTERCHANGE-US',
   'info' => $info
];

$user->create_node($body);
body := `{
  type: 'INTERCHANGE-US',
  info: {
    "nickname": "My Debit Card",
    "card_number": "Zoo8g2vBUjt7TwmEpRW8f6eQT3AOEEYePw2LkoxD+mO9lOT5OemHlGwgamgLGUbrmWu3DPwnEr2IqDy5YMFVgvQWP3w9nLOFzFFSW43auDgsVAqZScoRf8nI+6/B9KvOEV4XI8JeyXT+O+y3p3RtbiXGmYQNJ56Hy3hs2E5O+yn+3fpLfJQpVvNc38V+aE21VEsJuXFFNtS/8r4jJ6Dx/etTEaE/rtcEUEbwLLHFHjPiOWaHWZPuhXFLtyYrR9zG8FWSJVFwNTG/mEpv2O7We1iCB+9WoEKqdHyGwjjBcVgkUlU5huJIXv9xj53RGNvmHkDFTqgrlHpKkb0E/Ot0Zg==",
    "exp_date": "ctA4Zj1CP0WCiMefPYsyewVbIHNilfwA09X9NSCyWxft4WGwFZmZkhsBJh51QL751/iFkUHbd09ZpDYjS86PqyNPZ5LkBueGHDIghLwWyzH1l99RiIs8urOW9c4g3L1USD+kzzRAqG1DBkW47FAX6AhPSi3YgQd94ery1H+asaqDrP79ayzoJ+nRXeEqe83FIgNUk/J5+EcAz3JYnoBmp1sfz7a4zHkvk0eKCxQWLETdqvONyCZyXdC/4CkaCxJ/87VsN3i4+ToULtSluRv8xr1NpRhzipKiEKTYW1nvNDAaJQezTVP/+GxmTmQfnfpVNDpJbXjNrOTej1HgMFpg4w==",
    "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8"
  }
}`

data, err := user.CreateNode(body)

EXAMPLE RESPONSE

{
    "error_code": "0",
    "http_code": "200",
    "limit": 20,
    "node_count": 1,
    "nodes": [
        {
            "_id": "594e21fc4d1d62002f17e37d",
            "_links": {
                "self": {
                    "href": "https://uat-api.synapsefi.com/v3.1/users/594e0fa2838454002ea317a0/nodes/594e21fc4d1d62002f17e37d"
                }
            },
            "allowed": "CREDIT-AND-DEBIT",
            "client": {
                "id": "589acd9ecb3cd400fa75ac06",
                "name": "SynapseFI"
            },
            "extra": {
                "other": {},
                "supp_id": "ABC124"
            },
            "info": {
                "nickname": "Bank of America Debit Card",
                "card_hash": "5d20f6c392348ed604241bee015af14519d47cc1cb61c31a256973a8d75cf939",
                "document_id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8",
                "is_international": false,
                "network": "VISA",
                "type":"DEBIT"
            },
            "is_active": true,
            "timeline": [
                {
                    "date": 1498292731835,
                    "note": "Node created."
                }
            ],
            "type": "INTERCHANGE-US",
            "user_id": "594e0fa2838454002ea317a0"
        }
    ],
    "page_count": 1,
    "success": true
}

Verifying the Card
Upon linking a card, a 1¢ transaction will be debited from the card to verify the card. The 1¢ transaction will reflect as canceled on the user's statement within 1-2 business days.

Node Status
View all Node Statuses here.

Always Assign a Nickname

It is very important to assign a nickname to the INTERCHANGE-US node, because you can never retrieve the card_number back from the API.

Subscribe to Webhooks

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

Testing in Sandbox: Sample Card Numbers
Following are the sample card numbers that you can use to test out your INTERCHANGE-US implementation.

Card Number
Type
Network
Permission

9401100999999992

DEBIT

VISA

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9401101999999990

DEBIT

VISA

CREDIT

9401110999999991

DEBIT

VISA

DEBIT

9401113999999995

DEBIT

VISA

CREDIT-AND-DEBIT

9401200999999990

CREDIT

VISA

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9401201999999998

CREDIT

VISA

CREDIT

9401210999999999

CREDIT

VISA

DEBIT

9401211999999997

CREDIT

VISA

CREDIT-AND-DEBIT

9401300999999998

PREPAID

VISA

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9401301999999996

PREPAID

VISA

CREDIT

9401310999999997

PREPAID

VISA

DEBIT

9401311999999995

PREPAID

VISA

CREDIT-AND-DEBIT

9021100999999992

DEBIT

DISCOVER

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9021101999999990

DEBIT

DISCOVER

CREDIT

9021110999999991

DEBIT

DISCOVER

DEBIT

9021111999999999

DEBIT

DISCOVER

CREDIT-AND-DEBIT

9021200999999990

CREDIT

DISCOVER

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9021201999999998

CREDIT

DISCOVER

CREDIT

9021210999999999

CREDIT

DISCOVER

DEBIT

9021211999999997

CREDIT

DISCOVER

CREDIT-AND-DEBIT

9021300999999998

PREPAID

DISCOVER

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9021301999999996

PREPAID

DISCOVER

CREDIT

9021310999999997

PREPAID

DISCOVER

DEBIT

9021311999999995

PREPAID

DISCOVER

CREDIT-AND-DEBIT

9501100999999991

DEBIT

MASTERCARD

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9501101999999999

DEBIT

MASTERCARD

CREDIT

9501110999999990

DEBIT

MASTERCARD

DEBIT

9501111999999998

DEBIT

MASTERCARD

CREDIT-AND-DEBIT

9501200999999999

CREDIT

MASTERCARD

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9501201999999997

CREDIT

MASTERCARD

CREDIT

9501210999999998

CREDIT

MASTERCARD

DEBIT

9501211999999996

CREDIT

MASTERCARD

CREDIT-AND-DEBIT

9501300999999997

PREPAID

MASTERCARD

NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)

9501301999999995

PREPAID

MASTERCARD

CREDIT

9501310999999996

PREPAID

MASTERCARD

DEBIT

9501311999999994

PREPAID

MASTERCARD

CREDIT-AND-DEBIT

Encrypting Data

Please encrypt the card_number and exp_date on the client's device using our public key provided below.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzxVLeRTf77kmG/42SdjjtRfaI/7GN4UoUBfxzN80gCyrjK+tHYJR7DKefC47fNyA2dGU7x3tu1wQRKOkjschbC3ZWF1mCqccUiHRPiGhH9VBsxLbAUCFAKOPZcBDCT7IhUdd6S23e99ewkb0c6pRk28u+kz+7ZB7d6Z/S+Em316zs0HqEnEaoUNFXtdTyW3EPuaqo0+p9daICRC44VbrTlzc+Y1A/CsiOcCCl4ske8scu/fWg0K3nybfn7IdO2smkzRwwGOc4uexBMnAkAyl0eQrqXZO4vis6ktmLFV4NpYsd0U2vvmuXFoA9XBcJHdbAww/TGwHq5RJ3505QSEK8QIDAQAB
-----END PUBLIC KEY-----

JSencrypt is an easy to use library to use for this purpose, the implementation would look something like this:

// Encrypt with the public key...
var encrypt = new JSEncrypt();
encrypt.setPublicKey($('#pubkey').val());
var encryptedCardNumber = encrypt.encrypt($('#card_number').val());
var encryptedExpDate = encrypt.encrypt($('#exp_date').val());

Padding

Please make sure you are using PKCS1_v1_5 padding for encryption.

Card Type Restrictions

Platforms can request certain card types to be blocked. The types that may be blocked are DEBIT, CREDIT, PREPAID, DISCOVER, and AMEX.

{
  "error": {
    "en": "Currently PREPAID cards are not supported. Please link another card type."
  },
  "error_code": "200",
  "http_code": "400",
  "success": false
}

Link a Card


Link a credit or debit card

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.