Pull From Card
Request URL
POST /acquiring/pull
Description
This endpoint transfers money from a registered external card to your settlement account. Such transfers typically happen within seconds.
The /acquiring/pull 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 acquiring/pull
Property | Description | Required | Schema |
---|---|---|---|
amount | Amount | Yes | { "type": "number", "exclusiveMinimum": 0, "amountPrecision": 2, "$id": "common-amount" } |
cFiCardId | The card ID in connectFi | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z_]+$", "minLength": 1, "maxLength": 36, "$id": "common-id" } |
currency | A three character ISO alphabetic code to identify the currency | Yes | { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]+$", "$id": "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, "$id": "common-reference" } |
softDescriptor | An object containing additional details | No | toucan softDescriptor object |
Property table for toucan softDescriptor object
Property | Description | Required | Schema |
---|---|---|---|
address | Address details | Yes | toucan address object |
Email address | Yes | { "type": "string", "format": "email", "$id": "customer-email" } |
|
name | Name | Yes | { "type": "string", "maxLength": 22 } |
phone | Phone | Yes | toucan phone object |
Property table for toucan phone object
Property | Description | Required | Schema |
---|---|---|---|
countryCode | countryCode | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
number | Number | Yes | { "type": "string", "pattern": "^[0-9]+$", "minLength": 10, "maxLength": 10 } |
Property table for toucan address object
Property | Description | Required | Schema |
---|---|---|---|
addressLine1 | Line 1 of the address | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
addressLine2 | Line 2 of the address | No | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 0, "maxLength": 50, "nullable": true, "$id": "common-commonStr50" } |
city | City | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
state | State | Yes | { "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" } |
postalCode | Postal code | Yes | { "type": "string", "pattern": "^[0-9a-zA-Z-]+$", "minLength": 5, "maxLength": 10, "$id": "customer-postalCode" } |
country | Country | Yes | { "type": "string", "pattern": "^[A-Z]{2}$", "$id": "customer-countryCodeA2" } |
Request Body
{
"reference": "exrnl2TnId2605",
"cFiCardId": "tcrd_1AXvpht43m432u6UHpu07w",
"amount": 10.01,
"currency": "USD",
"narrative": "For invoice #123",
"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"
}
}
Snippet Examples
javascript
const axios = require('axios');
const data = {
"reference": "exrnl2TnId2605",
"cFiCardId": "tcrd_1AXvpht43m432u6UHpu07w",
"amount": 10.01,
"currency": "USD",
"narrative": "For invoice #123",
"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"
}
};
const config = {
method: 'POST',
url: '${CONNECTFI_BASE_URL}/acquiring/pull',
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/acquiring/pull" --data "{ \"reference\":\"exrnl2TnId2605\", \"cFiCardId\":\"tcrd_1AXvpht43m432u6UHpu07w\", \"amount\":10.01, \"currency\":\"USD\", \"narrative\":\"For invoice #123\", \"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\" } }" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"
Successful Response Examples
200 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": "exrnl2TnId2600",
"cFiCardId": "tcrd_1AXvpht43m432u6UHpu07w",
"amount": 10.01,
"currency": "USD",
"narrative": "For invoice #123",
"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"
}
}
RESPONSE BODY