Push To Card
Request URL
POST /transfer-to/card/push
Description
This endpoint sends money from your settlement account to a registered external card. Such transfers typically happen within seconds. The required request body properties are "reference", "cFiCardId", "amount", "currency", and "narrative". A "softDescriptor" object property is optional.
The /transfer-to/card/push endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate transactions. It is important to note that transactions submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following requests are not considered duplicates even though they are almost identical.
{
"reference": "EXT_REFERENCE_ID1", //different reference IDS
"cFiCardId": "tcrd_5m41U6ycdgJ5CNyGDObY8Q", //same cFiCardId
"amount": 1.01, //same amount
"currency": "USD",
"narrative": "Both of these transactions will be posted.",
"softDescriptor": {
"name": "Sample Merchant",
"address": {
"addressLine1": "1346 Pleasant Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "PA",
"postalCode": "12345",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5556667777"
},
"email": "merchant@sample.com"
}
}
{
"reference": "EXT_REFERENCE_ID2", //different reference IDS
"cFiCardId": "tcrd_5m41U6ycdgJ5CNyGDObY8Q", //same cFiCardId
"amount": 1.01, //same amount
"currency": "USD",
"narrative": "Both of these transactions will be posted.",
"softDescriptor": {
"name": "Sample Merchant",
"address": {
"addressLine1": "1346 Pleasant Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "PA",
"postalCode": "12345",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5556667777"
},
"email": "merchant@sample.com"
}
}
Schema
Property table for transfer-to/card/push
| Property | Description | Required | Schema |
|---|---|---|---|
| amount | amount | Yes | { "type": "number", "exclusiveMinimum": 0, "amountPrecision": 2, "description": "common-amount" } |
| cFiCardId | The card ID in connectFi | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z_]+$", "minLength": 1, "maxLength": 36, "description": "common-id" } |
| currency | A three character ISO alphabetic code to identify the currency | Yes | { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]+$", "description": "common-currency" } |
| narrative | A brief description | Yes | { "type": "string", "maxLength": 22 } |
| reference | An external alphanumeric reference ID for the entity in your system | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z]+$", "minLength": 1, "maxLength": 32, "description": "common-reference" } |
| softDescriptor | An object containing additional details | No | toucan softDescriptor object |
Property table for toucan address object
| Property | Description | Required | Schema |
|---|---|---|---|
| addressLine1 | addressLine1 | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| addressLine2 | addressLine2 | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "description": "common-commonStr50" } |
| city | city | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| state | state | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| postalCode | postalCode | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z-]+$", "minLength": 5, "maxLength": 10, "description": "customer-postalCode" } |
| country | country | Yes | { "type": "string", "pattern": "^[A-Z]{2}$", "description": "customer-countryCodeA2" } |
Property table for toucan phone object
| Property | Description | Required | Schema |
|---|---|---|---|
| countryCode | countryCode | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "description": "common-commonStr50Req" } |
| number | number | Yes | { "type": "string", "pattern": "^[0-9]+$", "minLength": 10, "maxLength": 10 } |
Property table for toucan softDescriptor object
| Property | Description | Required | Schema |
|---|---|---|---|
| address | An object containing address details | Yes | toucan address object |
| Email address | Yes | { "type": "string", "format": "email", "description": "customer-email" } |
|
| name | name | Yes | { "type": "string", "maxLength": 22 } |
| phone | phone | Yes | toucan phone object |
Request Body
{
"reference": "externalTrnId0500",
"cFiCardId": "tcrd_1AXvpht43m432u6UHpu07w",
"amount": 1.01,
"currency": "USD",
"narrative": "For invoice #123",
"softDescriptor": {
"name": "Sample Merchant",
"address": {
"addressLine1": "1346 Pleasant Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "12345",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5556667777"
},
"email": "merchant@sample.com"
}
}
Snippet Examples
javascript
const axios = require('axios');
const data = {
"reference": "externalTrnId0500",
"cFiCardId": "tcrd_1AXvpht43m432u6UHpu07w",
"amount": 1.01,
"currency": "USD",
"narrative": "For invoice #123",
"softDescriptor": {
"name": "Sample Merchant",
"address": {
"addressLine1": "1346 Pleasant Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "12345",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5556667777"
},
"email": "merchant@sample.com"
}
}
;
const config = {
method: 'POST',
url: '${CONNECTFI_BASE_URL}/transfer-to/card/push',
headers: {
'Content-Type': "application/json",
'x-connectfi-token': "A long random string token received from /auth/get-token request"
},
data
};
let result;
try {
result = await axios.request(config);
if (result.status === 200) {
console.log(JSON.stringify(result.data));
}
} catch (err) {
console.log({
errCode: err.code,
responseStatus: err.response && err.response.status,
data: err.response && JSON.stringify(err.response.data)
});
}
cURL
curl --location "CONNECTFI_BASE_URL/transfer-to/card/push" --data "{ \"reference\":\"externalTrnId0500\", \"cFiCardId\":\"tcrd_1AXvpht43m432u6UHpu07w\", \"amount\":1.01, \"currency\":\"USD\", \"narrative\":\"For invoice #123\", \"softDescriptor\":{ \"name\":\"Sample Merchant\", \"address\":{ \"addressLine1\":\"1346 Pleasant Ave\", \"addressLine2\":\"Apt A123\", \"city\":\"Salt Lake City\", \"state\":\"UT\", \"postalCode\":\"12345\", \"country\":\"US\" }, \"phone\":{ \"countryCode\":\"1\", \"number\":\"5556667777\" }, \"email\":\"merchant@sample.com\" } }" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"
Successful Response Examples
200 TRANSFER-TO/CARD/PUSH SUCCESSFUL RESPONSE
HEADERS
| Header | Value |
|---|---|
| Content-Type | application/json |
| x-connectfi-token | A long random string token received from /auth/get-token request |
REQUEST BODY
{
"reference": "externalTrnId0500",
"cFiCardId": "tcrd_1AXvpht43m432u6UHpu07w",
"amount": 1.01,
"currency": "USD",
"narrative": "For invoice #123",
"softDescriptor": {
"name": "Sample Merchant",
"address": {
"addressLine1": "1346 Pleasant Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "12345",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5556667777"
},
"email": "merchant@sample.com"
}
}
RESPONSE BODY