Wires
A wire transfer is a fast and reliable way of moving money between banks. As of now only US-domestic wires are supported.
| Endpoint or Section | Action |
|---|---|
| /transfer-to/wire | Send a wire transfer |
| Possible Status Values | List and descriptions of possible wire transfer status values |
| Testing Wires in the Sandbox | Describes specific property values that can be used to trigger error messages for testing |
| /transfer-to/wire/query | Query details of one or more wire transfers |
| /transfer-to/wire/list | List wire transfers by search criteria |
| Webhooks | Information about optional webhookURLs |
Send a Wire
Request method and URL:
POST /transfer-to/wire
Description:
This endpoint transfers funds from your bank (originator) to a specified account at another bank (beneficiary) within the U.S.
The /transfer-to/wire 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 wire transactions submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following wire transfers are not considered duplicates.
{
"amount": 1.01,
"currency": "USD",
"endUserAccount": "12345678901234567",
"reference": "EXT_REFERENCE_ID1", //Different reference IDS
"originator": {
"commonName": "John Doe",
"legalName": "John Doe",
"address": {
"addressLine1": "999 Main Street",
"addressLine2": "Ste. A",
"city": "San Francisco",
"state": "CA",
"postalCode": "12345",
"country": "US"
}
},
"beneficiary": {
"bankName": "Unicorn Bank",
"bankABANumber": "123456789",
"accountNumber": "12345678",
"name": "John Smith",
"address": {
"addressLine1": "1346 Pleasant Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "12345",
"country": "US"
}
},
"narrative": "Both of these wire transfers will post",
"memos": [
"Some message or note",
"Another message or note"
],
"webhookURL": "https://webhooktest.examplesite/9ec56257-5190-40a5-abc3-43f757b643abcc123"
}
{
"amount": 1.01,
"currency": "USD",
"endUserAccount": "12345678901234567",
"reference": "EXT_REFERENCE_ID2", //Different reference IDS
"originator": { //exact same originator details
},
"beneficiary": { //exact same beneficiary details
},
"narrative": "Both of these wire transfers will post",
"memos": [
"Some message or note",
"Another message or note"
],
"webhookURL": "https://webhooktest.examplesite/9ec56257-5190-40a5-abc3-43f757b643abcc123"
}
The required request body properties are described below:
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| amount | The requested wire transfer amount | number > 0 | 16.08 |
| currency | A three character ISO alphabetic code to identify the currency | string, regex pattern: "^[A-Z]{3}$" | "USD" |
| endUserAccount | The vAccount number that is used to fund the wire transfer | string | "12345678901234567" |
| reference | An external reference in your system (1-32 alphanumeric characters) | string, regex pattern: "^[0-9a-zA-Z]+$", max 32 characters | "externalTrnId331" |
| originator | The details of the sender of the wire transfer | object | see Originator Object below |
| beneficiary | The details of the recipient of the wire transfer | object | see Beneficiary Object below |
| narrative | A brief description of the transaction | string, regex pattern: "^.{1,500}$" | "Invoice #123 for May" |
| memos | An array containing notes made regarding the transaction (can be an empty array). Each memo is a string with max length 500. | array | see Request body example below |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| wireAccountToken | The wireAccountToken that corresponds to the desired account from which to transfer funds. If not included, the default wireAccountToken configuration for this client will be used. Contact support to add or update wireAccountToken configurations. | string | "123abc456DEF789" |
| webhookURL | URL which will be called after the wire transfer. If you specify a webhookURL in the /transfer-to/wire request, the system will perform a callback to your webhookURL every time the wire status changes. Refer to Webhooks for the callback format. |
string, regex pattern: "^.{1,500}$" | "https://webhooktest.examplesite/9ec56257-5190-40a5-abc3-43f757b643abcc123" |
Originator Object
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| commonName | Sender common name | string, regex pattern: "^.{1,50}$" | "John Doe" |
| legalName | Sender legal name | string, regex pattern: "^.{0,50}$" | "Acme, Inc." or "John Doe" |
| address | Sender address | object | see Address Object below |
Beneficiary Object
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| bankName | Recipient bank name | string, regex pattern: "^.{1,35}$" | "Unicorn Bank" |
| bankABANumber | Recipient bank ABA routing number, each # represents a digit 0-9 | string, regex pattern: "^.{1,34}$" | "#########" |
| accountNumber | Recipient account number, each # represents a digit 0-9 | string, regex pattern: "^.{1,50}$" | "#########" |
| name | Recipient name | string, regex pattern: "^.{1,50}$" | "John Smith" |
| address | Recipient address | object | see Address Object below |
Address Object
| Properties | Description | Schema | Example Values |
|---|---|---|---|
| addressLine1 | Address line 1 (required) | string, regex pattern: "^.{1,35}$" | "1346 Some Ave" |
| addressLine2 | Address line 2 (optional, nullable) | string, regex pattern: "^.{0,35}$" | "Apt A123" |
| city | City (required) | string, regex pattern: "^.{1,50}$" | "Salt Lake City" |
| state | State (required) | string, regex pattern: "^.{1,50}$" | "UT" |
| postalCode | Postal code (required), each # represents a digit 0-9, must be a valid postal code | string, 5-10 characters | "#####" |
| country | Country (required) | string, regex pattern: "^.{1,50}$" | "US" |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
{
"amount": 16.08, //transaction amount
"currency": "USD", //currency code
"endUserAccount": "12345678901234567", //vAccount number used to fund the transfer
"reference": "externalTrnId332", //unique ID in the client system
"originator": { //source that funds are transferred from
"commonName": "John Doe", //name of sender
"legalName": "John Doe", //legal name of sender
"address": { //address of sender
"addressLine1": "999 Some Street",
"addressLine2": "Ste. A",
"city": "San Francisco",
"state": "CA",
"postalCode": "#####", //a postal code (5-9 digits is typical for the US), ##### is used as a placeholder here for documentation purposes
"country": "US"
}
},
"beneficiary": { //bank that funds are transferred to
"bankName": "Unicorn Bank",
"bankABANumber": "#########", //a US ABA account routing number of the beneficiary bank, ######### is used as a placeholder here for documentation purposes
"accountNumber": "########", //account # at the beneficiary bank, ######## is used as a placeholder for documentation purposes
"name": "John Smith", //name of beneficiary
"address": { //address of beneficiary
"addressLine1": "1346 Some Ave",
"addressLine2": "Apt A123",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "#####", //a postal code (5-9 digits is typical for the US), ##### is used as a placeholder here for documentation purposes
"country": "US"
}
},
"narrative": "Invoice #123 for May", //brief description of the wire transfer
"memos": [ //array containing notes (as string values) regarding the transaction (can be [])
"For spare parts as per contract #123",
"Delivered to Salt Lake City UT US 12345"
],
"webhookURL": "https://webhooktest.examplesite/9ec56257-5190-40a5-abc3-43f757b643abcc123" //optional webhookURL for callback
}
Possible responses:
200 (HTTP response status code) -- Request for wire transfer was accepted and will be processed. A connectFi ID is assigned to the transaction.
{
"code": "0", //Success
"data": {
"reference": "externalTrnId332", //reference from request
"cFiTransactionId": "evolve_6jdlcIq57J7JFluJoPXuwM", //transaction ID in connectFi
"amount": 16.08, //transaction amount
"currency": "USD", //currency code
"transactionReceiptId": "JW2QGEHYI0", //transaction receipt ID from the back office
"status": "Initiated", //current status in connectFi
"dtsCreatedAt": "2022-10-25T19:10:23.000Z" //date created
},
"requestId": "cf4d0c20f0ea11ed908956da8a865bbc"
}
200 (HTTP response status code) -- Insufficient funds:
If a wire will exceed the current available balance, then the transaction will be saved as "Initiated", an alert will be sent to ensure that the correct balance is available, and the wire will be reattempted.
The alert sent will include the following.
subject: "Wire Amount will exceed available balance",
text: `Wire initialized, but not yet sent. Will retry sending wire. Please ensure correct balance is available.\r\n
cFiAggregatorId: evolve \r\n
wireMerchantId: 1234567890 \r\n
amount: $16.97 \r\n
currency: USD \r\n`
The returned response:
{
"code": "0",
"data": {
"reference": "externalTrnId1458",
"cFiTransactionId": "evolve_YEhoCaCSN6tNyRk6ETJjY",
"amount": 16.97,
"currency": "USD",
"status": "Initiated",
"dtsCreatedAt": "2023-11-09T14:27:35.087Z"
},
"requestId": "202254c07f0c11ee9e3bd5975edcd412"
}
400 (HTTP response status code) -- Incorrect input data:
{
"requestId": "fa057350f0ed11ed908956da8a865bbc",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": {
"missingProperty": "amount"
},
"message": "must have required property 'amount'"
}
]
}
400 (HTTP response status code) -- Reference is not unique:
In this example, the reference ID was already used on a previous transaction. Reference must be unique
{
"requestId": "ae0e57407f0a11ee9e3bd5975edcd412",
"code": "referenceExists",
"context": {
"entityId": "chk_5f2pO0aq0I5D0HV440yms2",
"reference": "extChkRef00000006"
},
"message": "Reference already exists."
}
400 (HTTP response status code) -- Invalid Source Account:
{
"requestId": "4d6b3e30f0ee11ed908956da8a865bbc",
"code": "extWire",
"context": {
"status": "Declined",
"cFiTransactionId": "evolve_2m67esqizhQnmGvvu9jqJ2",
"cFiAggregatorId": "evolve",
"reference": "externalTrnId1291", //reference from request
"amount": 16.98, //set sandbox value to test "Invalid Source Account" error message
"dtsError": "2023-05-12T17:56:22.000Z" //date of request
},
"message": "Invalid Source Account."
}
400 (HTTP response status code) -- Core System downstream error:
{
"requestId": "8f097dc0f0ee11ed908956da8a865bbc",
"code": "extWire",
"context": {
"status": "Declined",
"cFiTransactionId": "evolve_4lUNtZjmmdLPGfJXjxIAYw",
"cFiAggregatorId": "evolve",
"reference": "externalTrnId1293", //reference from request
"amount": 16.99, //set sandbox value to test "Core System downstream error. Wire not created." error message
"dtsError": "2023-05-12T17:58:13.000Z" //date of request
},
"message": "Core System downstream error. Wire not created."
}
400 (HTTP response status code) -- Wire Amount will exceed Account Daily Total Amount Limit:
{
"requestId": "dc7966307f0d11ee9e3bd5975edcd412",
"code": "wireAmountDailyLimit",
"context": {
"status": "Declined",
"cFiTransactionId": "evolve_6I2PVnSJ8pLgie7hdSyoWS",
"cFiAggregatorId": "evolve",
"reference": "externalTrnId1461",
"amount": 17.01 //set sandbox value to amount > 17.00 and <= 18.00 in order to test this error message
},
"message": "Wire Amount will exceed Account Daily Total Amount Limit. Wire not created."
}
400 (HTTP response status code) -- Wire Amount Exceeds Limit for the Wire Account:
{
"requestId": "02eefaf07f0e11ee9e3bd5975edcd412",
"code": "wireAmountDailyLimit",
"context": {
"status": "Declined",
"cFiTransactionId": "evolve_5xKV5OX5rNIVgABlT9YGK",
"cFiAggregatorId": "evolve",
"reference": "externalTrnId1462",
"amount": 18.01 //set sandbox value to amount > 18.00 and <= 19.00 in order to test this error message
},
"message": "Wire Amount Exceeds Limit for the Wire Account. Wire not created."
}
400 (HTTP response status code) -- Wire Amount will exceed Company Daily Total Limit:
{
"requestId": "7fdf3bb07f0e11ee9e3bd5975edcd412",
"code": "wireAmountDailyLimit",
"context": {
"status": "Declined",
"cFiTransactionId": "evolve_3TisD1qBlmLFebZi8SS3dM",
"cFiAggregatorId": "evolve",
"reference": "externalTrnId1464",
"amount": 19.01 //set sandbox value to amount > 19.00 and <= 20.00 in order to test this error message
},
"message": "Wire Amount will exceed Company Daily Total Limit. Wire not created."
}
400 (HTTP response status code) -- Wire Amount exceeds Company Wire Amount Limit:
{
"requestId": "ba53fc407f0e11ee9e3bd5975edcd412",
"code": "wireAmountDailyLimit",
"context": {
"status": "Declined",
"cFiTransactionId": "evolve_5FCcZ2pRCAlbtzZotqlpwm",
"cFiAggregatorId": "evolve",
"reference": "externalTrnId1465",
"amount": 20.01 //set sandbox value to amount > 20.00 in order to test this error message
},
"message": "Wire Amount exceeds Company Wire Amount Limit. Wire not created."
}
400 (HTTP response status code) -- Cannot send a wire request for $0 or less
{
"requestId": "cc954250f0ee11ed908956da8a865bbc",
"code": "requestValidateError",
"context": [
{
"instancePath": "/amount",
"schemaPath": "common#/definitions/amount/exclusiveMinimum",
"keyword": "exclusiveMinimum",
"params": {
"comparison": ">",
"limit": 0
},
"message": "must be > 0"
}
]
}
400 (HTTP response status code) -- Module wire is disabled
This service has not been enabled for the client. Contact your PayGears Corporation representative to request wire services.
{
"requestId": "a6b33dc07f0611ee9e3bd5975edcd412",
"code": "moduleDisabled",
"message": "Module wire is disabled"
}
400 (HTTP response status code) -- The wireAccountToken specified in the request is not found
The wireAccountToken property was included in the request body with a value that has not been configured. Contact PayGears support in order to add additional wire configurations. If the wireAccountToken property is not included in the request body, then the default wire configuration will be used if one has been enabled.
{
"requestId": "67c471507f0711ee9e3bd5975edcd412",
"code": "uniqueAttributeNotFound",
"message": "Unique Attribute wireAccountToken=_______________ not found for module wire"
}
Possible Status Values
| Value of status property | Description |
|---|---|
| Initiated | A /transfer-to/wire request has successfully created the wire transfer and returned the cFiTransactionId that was created. When the status changes, the webhook will be called if applicable. |
| Complete | A "Complete" status indicates that PayGears has received a response that the wire transfer request was completed successfully. |
| Declined | A "Declined" status indicates that PayGears has received a response that the wire transfer failed. |
| Unknown/Manual | An "Unknown" or "Manual" status indicates that PayGears has received an unexpected response and a manual review will need to take place. Please contact support. |
Testing Wires in the Sandbox
To check error messages, there are specific amounts in the sandbox that will trigger set error messages. You can test these errors using the following values:
| Property | Value | Error Message |
|---|---|---|
| amount | 16.97 | "Amount Exceeds Balance." |
| amount | 16.98 | "Invalid Source Account." |
| amount | 16.99 | "Core System downstream error. Wire not created." |
| amount | 12.91 | Initial transaction status will be "Initiated" and status will resolve to "Complete" when triggered by a /transfer-to/wire/query request. When the status resolves, the webhook will be called if applicable and a "Complete" status returned. If no webhook was included in the request, you can also use /transfer-to/wire/query a second time to check the status resolution. |
| amount | 12.92 | Initial transaction status will be "Initiated" and status will resolve to "Declined" when triggered by a /transfer-to/wire/query request. When the status resolves, the webhook will be called if applicable and a "Declined" status returned. If no webhook was included in the request, you can also use /transfer-to/wire/query a second time to check the status resolution. |
Query Wires
Request method and URL:
POST /transfer-to/wire/query
Description:
The status of up to 20 wire transfers may be requested at a time. The requested transfers are identified either by an array of connectFi transaction IDs ("cFiTransactionIds") or by an array of external system "references". The array that you include may not be an empty array.
The system will return only the wire transfers it could locate. Unknown IDs will be ignored and if no IDs are recognized, an empty array is returned with success code "0".
If the same ID is requested multiple times in the "сFiTransactionIds" or "references" array, the response will only return one object in the data array corresponding to that ID, regardless of how many times it was listed in the request array.
If more than 20 elements are listed in the request array (either "сFiTransactionIds" array or the "references" array), an error will be thrown even if the IDs are not unique. For example, if the cFiTransactionId "amplifi-6UkLq66HEN6IMj4fNl6hgM" is listed 21 times in the request array, the request will fail even though technically only one unique ID was requested.
Either "cFiTransactionIds": [...] should be used or "references": [...], but not both. You cannot combine both types of IDs into a single request.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiTransactionIds | Array of transaction IDs from the connectFi system obtained when each transaction was initialized | array | ["evolve_2Pbz8EZgeMroFVx05nKQxq", "evolve_3iObPFig64JLcNQNApDqGs", "evolve_44wbIQLZZl4LCSPDqO3qKQ"] |
OR
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| references | Array of external reference IDs from your system that you entered when initializing the wire transfers | array | ["externalTrnId331", "externalTrnId332"] |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example (using connectFi transaction IDs):
{
"сFiTransactionIds": ["evolve_4UtYecKI3MpmKl4WCFVoi4", "evolve_5gqB8D9JBMR5TI1bNvdSfC"] //array of cFiTransactionIds
}
Request body example (using external system references):
Possible responses:
200 (HTTP response status code) -- Wire statuses are returned
In this example, the request was made using the "сFiTransactionIds" key:value pair. The array of IDs requested was ["evolve_4UtYecKI3MpmKl4WCFVoi4", "evolve_5gqB8D9JBMR5TI1bNvdSfC"]. Only one record will be returned for each cFiTransactionId, even if the same ID occurs multiple times in the request array.
{
"code": "0", //Success
"data": [
{
"status": "Initiated", //or "Complete" or "Declined"
"amount": 16.08, //transaction amount
"currency": "USD", //currency code
"reference": "externalTrnId331", //external ID
"cFiTransactionId": "evolve_4UtYecKI3MpmKl4WCFVoi4", //transaction ID in connectFi
"transactionReceiptId": "JW2QGEH456", //transaction receipt ID from the back office
"dtsCreatedAt": "2022-10-25T19:10:04.000Z" //date created
},
{
"status": "Initiated", //or "Complete" or "Declined"
"amount": 10.98, //transaction amount
"currency": "USD", //currency code
"reference": "externalTrnId332", //external ID
"cFiTransactionId": "evolve_5gqB8D9JBMR5TI1bNvdSfC", //transaction ID in connectFi
"transactionReceiptId": "JW2QGEH789", //transaction receipt ID from the back office
"dtsCreatedAt": "2022-10-25T19:10:23.000Z" //date created
}
],
"requestId": "a799fc10f0ef11ed908956da8a865bbc"
}
200 (HTTP response status code) -- Wire statuses are returned
In this example, the request was made using the "references" key:value pair. The two external reference IDs that were requested are "externalTrnId331" and "externalTrnId332".
{
"code": "0", //Success
"data": [
{
"status": "Initiated", //or "Complete" or "Declined"
"amount": 16.08, //transaction amount
"currency": "USD", //currency code
"reference": "externalTrnId331", //external ID
"cFiTransactionId": "evolve_4UtYecKI3MpmKl4WCFVoi4", //transaction ID in connectFi
"transactionReceiptId": "JW2QGEH456", //transaction receipt ID from the back office
"dtsCreatedAt": "2022-10-25T19:10:04.000Z" //date created
},
{
"status": "Initiated", //or "Complete" or "Declined"
"amount": 10.98, //transaction amount
"currency": "USD", //currency code
"reference": "externalTrnId332", //external ID
"cFiTransactionId": "evolve_5gqB8D9JBMR5TI1bNvdSfC", //transaction ID in connectFi
"transactionReceiptId": "JW2QGEH789", //transaction receipt ID from the back office
"dtsCreatedAt": "2022-10-25T19:10:23.000Z" //date created
}
],
"requestId": "a799fc10f0ef11ed908956da8a865bbx"
}
200 (HTTP response status code) -- сFiTransactionIds/references requested do not exist
In this example, the request was successful but the requested transaction IDs do not exist in connectFi.
400 (HTTP response status code) -- Must not have additional properties
In this example, the request contained both a "cFiTransactionIds" key:value pair and a "references" key:value pair. The two types of IDs cannot be combined into a single request and will throw an error.
{
"requestId": "197b1f30f0f011ed908956da8a865bbc",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/oneOf/0/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "references"
},
"message": "must NOT have additional properties"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "cFiTransactionIds"
},
"message": "must NOT have additional properties"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code) -- Cannot request an empty array of external reference IDs (or an empty array of cFiTransactionIds)
In this example, an empty "references" array was included in the request.
{
"requestId": "549e9650f0f011ed908956da8a865bbc",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/oneOf/0/required",
"keyword": "required",
"params": {
"missingProperty": "cFiTransactionIds"
},
"message": "must have required property 'cFiTransactionIds'"
},
{
"instancePath": "/references",
"schemaPath": "#/oneOf/1/properties/references/minItems",
"keyword": "minItems",
"params": {
"limit": 1
},
"message": "must NOT have fewer than 1 items"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code) -- Must not have fewer than 1 characters
In this example, an empty string ("") was included in the cFiTransactionIds array, along with several valid IDs.
{
"requestId": "bff587b0f0f011ed908956da8a865bbc",
"code": "requestValidateError",
"context": [
{
"instancePath": "/cFiTransactionIds/0",
"schemaPath": "common#/definitions/id/minLength",
"keyword": "minLength",
"params": {
"limit": 1
},
"message": "must NOT have fewer than 1 characters"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/required",
"keyword": "required",
"params": {
"missingProperty": "references"
},
"message": "must have required property 'references'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code)
List Wire Transfers
Request method and URL:
POST /transfer-to/wire/list
Description:
This endpoint will list wire transfers that match the desired search criteria. Search criteria may be a date range, a status value, or a combination of criteria. You may also specify a maximum number of records to return using the numberOfRecords property (up to 1000) and you may specify a number of records to skip using the skipRecords property. Combine the numberOfRecords property with the skipRecords property to make displaying wire transfer lists in batches easy. For example, if you want to list wire transfers in batches of 150, you can set numberOfRecords to 150 and skipRecords to 0 in the first request. Then, increase skipRecords by 150 in each subsequent request to return the next batch and so on.
When making a request, if the number of wire transfers matching the criteria is greater than the numberOfRecords maximum requested, the response body will indicate that there are additional wire transfers ("more": true).
If no properties are included, an unfiltered wire transfer list will be returned (up to a maximum of 1000).
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| dateCreateFrom | A beginning date in ISO Date format, if using a date range to list transactions, nullable | string | "2023-05-10T12:46:31.578Z" |
| dateCreateTo | An ending date in ISO Date format, if using a date range to list transactions, nullable | string | "2023-05-13T12:46:31.578Z" |
| status | The desired status for which to search, nullable | string | "Initiated", "Complete", "Declined", "Unknown", or "Manual" |
| numberOfRecords | The maximum number of desired records to return, nullable | integer <=1000 | 850 |
| skipRecords | The number of records to skip when returning results, nullable | integer | 25 |
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
Request body (using a date range)
Request body (using a combination of desired search criteria)
{
"dateCreateFrom": "2023-04-01T14:27:33.684Z", //beginning of requested date range
"dateCreateTo": "2023-05-12T14:27:33.684Z", //end of requested date range
"status": "Initiated", //will only return transactions with an "Initiated" status
"numberOfRecords": 15, //will return up to a maximum of 15 records
"skipRecords": 1 //will skip the first transaction found
}
Possible responses:
200 (HTTP response status code) -- Success, wire transfers that meet the search criteria will be returned.
{
"code": "0", //Success
"data": {
"total": {
"skipRecords": 0, //the number of records that were skipped
"numberOfRecords": 6, //maximum number of records requested
"more": false //true if the number of records found is greater than the "numberOfRecords" requested
},
"items": [
{
"status": "Initiated", //current transaction status
"amount": 1.01, //amount transferred
"currency": "USD", //currency code
"reference": "externalTrnId1298", //external reference from your system
"cFiTransactionId": "evolve_4RDlUqQDD8jogCJegVc9D2", //transaction ID in connectFi
"transactionReceiptId": "JW2QGEHYI0",
"dtsCreatedAt": "2023-05-12T18:05:48.809Z" //date created
},
{
"status": "Initiated", //current transaction status
"amount": 15.32, //amount transferred
"currency": "USD", //currency code
"reference": "externalTrnId1297", //external reference from your system
"cFiTransactionId": "evolve_44wbIQLZZl4LCSPDqO3qKQ", //transaction ID in connectFi
"transactionReceiptId": "JAIDGEHEV0",
"dtsCreatedAt": "2023-05-12T18:05:05.150Z" //date created
},
{
"status": "Initiated", //current transaction status
"amount": 12.0, //amount transferred
"currency": "USD", //currency code
"reference": "externalTrnId1295", //external reference from your system
"cFiTransactionId": "evolve_2Pbz8EZgeMroFVx05nKQxq", //transaction ID in connectFi
"transactionReceiptId": "JIGGEHEIW1",
"dtsCreatedAt": "2023-05-12T18:03:56.384Z" //date created
}
//rest of returned transactions, if any
]
},
"requestId": "b0bfb8e0f0f211ed908956da8a865bbc"
}
200 (HTTP response status code) -- Success, no transactions that meet the search criteria were found.
Note: If the dateCreateTo date is before the dateCreateFrom date, you will receive the same response. Check to make sure the date range is valid if no transactions meet your criteria when transactions are expected.
{
"code": "0",
"data": {
"total": {
"skipRecords": 0,
"numberOfRecords": 0,
"more": false
},
"items": []
},
"requestId": "85f558b0f0e111ed9bc156da8a861818"
}
400 (HTTP response status code) -- numberOfRecords field greater than 1000
In this example, the number of maximum records requested was greater than 1000.
{
"requestId": "d7ed5d207f0711ee9e3bd5975edcd412",
"code": "greaterNumberOfRecords",
"context": {
"maxNumberOfRecords": 1000
},
"message": "Bad request. numberOfRecords field greater than 1000"
}
400 (HTTP response status code) -- Must be equal to one of the allowed values
In this example, an invalid status value was requested.
{
"requestId": "0df80cd07f0811ee9e3bd5975edcd412",
"code": "requestValidateError",
"context": [
{
"instancePath": "/status",
"schemaPath": "#/properties/status/enum",
"keyword": "enum",
"params": {
"allowedValues": [
"Sent",
"Initiated",
"Complete",
"Declined",
"Unknown"
]
},
"message": "must be equal to one of the allowed values"
}
]
}
Webhooks
While sending a wire, if a webhookURL is included in the request, connectFi will make exactly one attempt to do a callback to the webhookURL every time the wire status changes.
The callback will consist of a POST request to the URL you specified with the following body:
{
"status": "Complete", //or "Declined"
"amount": 1.01, //transaction amount
"currency": "USD", //currency code
"reference": "externalTrnId01", //unique ID in the client system
"cFiTransactionId": "evolve_3iObPFig64JLcNQNApDqGs", //transaction ID in connectFi
"transactionReceiptId": "JW2QGEHYI0", //transaction receipt ID from the back office
"dtsCreatedAt": "2022-07-15T15:12:59.110Z", //date created
"dtsCompleted": "2022-07-15T15:12:59.110Z" //date completed
}