Skip to content

Unified Payments

This service allows ACH transfers, wire transfers, and push/pull to card transactions, all from a single, unified API endpoint.

Endpoint or Section Action
Encrypting Card Data Instructions for encrypting sensitive card data before registering an external card
/transfer-to/combo/card/register Register card to enable push/pull transactions for the card
/transfer-to/combo/create Create a transaction (either ACH, wire, pull from card, or push to card)
Additional Actions Available to Unified Card Payments Transactions List and descriptions of actions available for transactions created using the unified card payments endpoint
Possible Status Values List and descriptions of possible transfer status values
Webhooks Information about optional webhookURLs

Register an External Card

Request method and URL:

POST /transfer-to/combo/card/register

Description:

Once the external card data is encrypted, this endpoint will register it in the connectFi database.

The /transfer-to/combo/card/register 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 registrations. It is important to note that card registrations 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 refer to the same card data. If both of these requests are processed, there will be two separate registrations with two separate reference IDs for the same external card.

{
  "reference": "EXT_REFERENCE_ID1", //Different reference IDS
  "card": {
    "encryptedData": "u5zl2moWuA...gFNLRg", //exact same encryption data
    "keyId": "h123...abcw" //exact same key ID
  },
  "owner": { //same owner details
    "name": {
      "first": "John",
      "middle": "M",
      "last": "Doe",
      "suffix": "III"
    },
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    }
  }
}

{
  "reference": "EXT_REFERENCE_ID2", //Different reference IDS
  "card": {
    "encryptedData": "u5zl21234...gFNLRg", //exact same encryption data
    "keyId": "h123...abcw" //exact same key ID
  },
  "owner": { //same owner details
    "name": {
      "first": "John",
      "middle": "M",
      "last": "Doe",
      "suffix": "III"
    },
    "address": {
      "addressLine1": "1346 Pleasant Ave",
      "addressLine2": "Apt A123",
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "12345",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1234567890"
    }
  }
}

The request body properties for this endpoint are:

Required Properties Description Schema Example Values
card The external card being registered, consisting of the encrypted data and a keyId object see Card Object below
owner The card holder details object see Owner Object below
reference An external alphanumeric reference ID (1-32 characters) for the card in your system string, regex pattern: ^[0-9a-zA-Z]+$ "externalCardId02"

Card Object

Required Properties Description Schema Example Values
encryptedData A long string containing the encrypted card data string, regex pattern: ^.{1,500}$ see Encrypting Card Data
keyId The ID of your public key string, regex pattern: ^.{1,50}$ "123"

Owner Object

Required Properties Description Schema Example Values
address The card holder's address object see Address Object below
name The card holder's name object see Name Object below
phone The card hold's phone number object see Phone Object below

Address Object

Properties Description Schema Example Values
addressLine1 Cardholder address line 1 (required) string, regex pattern: ^.{1,50}$ "1346 Some Ave"
addressLine2 Cardholder address line 2 (optional) string, regex pattern: ^.{0,50}$ "Apt A123"
city Cardholder city (required) string, regex pattern: ^.{1,50}$ "Salt Lake City"
state Cardholder state (required) string, regex pattern: ^.{1,50}$ "UT"
postalCode Cardholder postal code (required), each # represents a digit 0-9 string, regex pattern: "^[0-9a-zA-Z-]{5,10}$" "#####"
country Cardholder country (required) string, regex pattern: ^[A-Z]{2}$ "US"

Name Object

Properties Description Schema Example Values
first Cardholder first name (required) string, regex pattern: ^.{1,50}$ "John"
last Cardholder last name (required) string, regex pattern: ^.{1,50}$ "Doe"
middle Cardholder middle name (optional, nullable) string, regex pattern: ^.{0,50}$ "M"
suffix Cardholder suffix (optional, nullable) string, regex pattern: ^.{0,50}$ "III"

Phone Object

Required Properties Description Schema Example Values
countryCode Cardholder phone country code string, regex pattern: ^.{1,4}$ "1"
number Cardholder 10 digit phone number, each # represents a digit 0-9 string, regex pattern: ^[0-9]{10}$ "##########"

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

{
  "reference": "externalCardId01", //unique ID of the card in the client system 
  "card": {
    "encryptedData": "<encryptedData", //PAN, expiry, CVV as a long encryption string
    "keyId": "123" //ID of your public key
  },
  "owner": { //cardholder
    "name": {
      "first": "John",
      "middle": "M", //optional
      "last": "Doe",
      "suffix": "III" //optional
    },
    "address": {
      "addressLine1": "1346 Some Ave",
      "addressLine2": "Apt A123", //optional
      "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"
    },
    "phone": {
      "countryCode": "1",
      "number": "##########" //a phone number (10 digits for the US), ########## is used as a placeholder here for documentation purposes
    }
  }
}

The same card can be registered multiple times.

Possible responses:

200 (HTTP response status code) -- Success, request for registering a card was accepted and will be processed:

{
    "code": "0", //Success
    "data": {
        "cFiCardId": "tcrd_5F6cM6PnllBKutxDb10gqY", //card ID in connectFi
        "dtsRegistered": "2023-05-15T14:56:52.407Z", //date registered
        "reference": "externalCardId50", //give external reference
        "isPullEnabled": true, //True if pull transactions are enabled for the card
        "isPushEnabled": true, //True if push transactions are enabled for the card
        "cardExpirationDate": "202512", //Card expiration date
        "cardLast4": "1234" //Last 4 digits of the card number
    },
    "requestId": "b8f66a50f33011eda84f56da8a8643b8"
}

400 (HTTP response status code) -- Duplicate cardReference:

{
    "requestId": "0493e350684f11ee8df9d847b134c812",
    "code": "referenceExists",
    "context": {
        "reference": "externalCardId60"
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Incorrect input data:

{
    "requestId": "8b376090f33211eda84f56da8a8643b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "card"
            },
            "message": "must have required property 'card'"
        }
    ]
}

400 (HTTP response status code) -- Invalid keyId value

This example shows the response when the request body contains an invalid keyId value.

{
    "requestId": "95a953d0f33211eda84f56da8a8643b8",
    "code": "extToucan",
    "subCode": 400,
    "context": {
        "errorCode": "3C3E1402"
    },
    "message": "card.keyID"
}

400 (HTTP response status code) -- Other errors:

{
    "code": "<not zero code>",
    "message": "Some error"
}

Back to Top

Create a Transaction

Request method and URL:

POST /transfer-to/combo/create

Description:

This endpoint allows the creation of either an ACH transfer, a wire transfer, a pull from card transaction, or a push to card transaction. The request body is dependent on the type of transaction requested, with the addition of a transferType field.

The /transfer-to/combo/create 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 registrations. It is important to note that card registrations submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values.

Required Properties Description Schema Example Values
transferType The type of transaction requested string "ach", "wire", "pull", or "push"

Additional required and optional properties are dependant on the type of transaction requested. See the following table for properties specific to the desired transaction type.

Type of Transfer Documentation of Additional Request Body Properties
ach Include the transferType property, in addition to the ACH required and optional properties.
wire Include the transferType property, in addition to the wires required and optional properties.
pull Include the transferType property, in addition to the pull from card required and optional properties.
push Include the transferType property, in addition to the push to card required and optional properties.

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

Example of an ACH transfer request

{
    "transferType": "ach", //type of transaction
    "reference": "extTrnAch155", //external reference in the client system
    "effectiveEntryDate": "2023-06-30", //future date for the ACH transfer
    "standardEntryClassCode": "WEB", //SEC code for the transaction
    "individualName": "John Smith",
    "routingNumber": "123456789",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking", 
    "transactionType": "Credit", //or "Debit"
    "amount": 3.15,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://webhook.site/53f3a57e-e8b7-4b1b-af99-fa340c2e2b94"
}

See Standard Entry Class Codes Table for a description of SEC codes and their requirements.

Example of a wire transfer request

{
    "transferType": "wire", //type of transaction
    "amount": 1.01,
    "currency": "USD",
    "reference": "externalWTrnId13055", //external reference in the client system
    "originator": {
        "commonName": "John Doe",
        "legalName": null,
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "123456789",
        "accountNumber": "123456789",
        "name": "John Smith",
        "address": {
            "addressLine1": "1234 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Invoice #123 for May",
    "memos": [
        "For spare parts as per contract ##123",
        "Delivered to Salt Lake City UT US 12345"
    ],
    "webhookURL": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f"
}

Example of a pull from card transaction request

{
  "transferType": "pull", //type of transaction
  "reference": "exrnlPllTnId25870", //external reference in the client system
  "cFiCardId": "tcrd_67KLZavYtIY7qp0Dw9Jy0o", //card ID in the connectFi system
  "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": "84111",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "4345156001"
    },
    "email": "merchant@sample.com"
  } 
}

Example of a push to card transaction request

{
    "transferType": "push", //type of transaction
    "reference": "externalPshTrnId0361", //external reference in the client system
    "cFiCardId": "tcrd_7kQwVPPTyvdtPWYJC793qQ", //card ID in the connectFi system
    "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": "84111",
          "country": "US"
        },
        "phone": {
          "countryCode": "1",
          "number": "4345156001"
        },
        "email": "merchant@sample.com"
    } 
}

Possible responses:

200 (HTTP response status code) -- Request for transfer was accepted and will be processed. A connectFi ID is assigned to the transaction.

Example of an ACH transfer response

{
    "code": "0", //Success
    "data": {
        "cFiTransactionId": "amplifi_3BkUqo0FanZtLaOndFbp16",
        "reference": "extTrnAch155",
        "cFiAggregatorId": "amplifi",
        "clientCode": "VALENTYN",
        "isInternal": false,
        "effectiveEntryDate": "2023-06-30",
        "standardEntryClassCode": "WEB",
        "companyEntryDescription": "PAYMENT",
        "individualName": "John Smith",
        "routingNumber": "123456789",
        "DFIAccountNumber": "123456789",
        "accountType": "Checking",
        "transactionType": "Credit",
        "amount": 3.15,
        "currency": "USD",
        "addenda05": [],
        "webhookUrl": "https://webhook.site/53f3a57e-e8b7-4b1b-af99-fa340c2e2b94",
        "status": "Initiated",
        "dtsCreatedAt": "2023-06-29T14:37:24.273Z",
    },
    "requestId": "76551750168a11eeb55456da8a861db0"
}

Example of a wire transfer response

{
    "code": "0", //Success
    "data": {
        "reference": "externalWTrnId13055",
        "cFiTransactionId": "amplifi_7538ilSCyZ8wvzXkyAEpTm",
        "amount": 1.01,
        "currency": "USD",
        "status": "Initiated",
        "dtsCreated": "2023-06-29T14:47:45.538Z"
    },
    "requestId": "e883efd0168b11eeb55456da8a861db0"
}

Example of a pull from card transaction response

{
    "code": "0", //Success
    "data": {
        "reference": "exrnlPllTnId25870",
        "cFiTransactionId": "amplifi_6xB9N17pKZI16G2nYDeLY4",
        "dtsCreated": "2023-06-29T14:54:25.252Z",
        "status": "Complete",
        "network": "Visa",
        "networkRC": "00"
    },
    "requestId": "d6ef3ee0168c11eeb55456da8a861db0"
}

Example of a push to card transaction response

{
    "code": "0", //Success
    "data": {
        "reference": "externalPshTrnId0363",
        "cFiTransactionId": "amplifi_54hGywCjSYBVjcFueybwkE",
        "dtsCreated": "2023-06-29T14:53:04.064Z",
        "status": "Complete",
        "network": "Visa",
        "networkRC": "00"
    },
    "requestId": "a68c5030168c11eeb55456da8a861db0"
}
Type of Transfer Additional documentation for possible responses
ach View the Possible Responses section in Send an ACH Transfer for additional documentation regarding ACH responses, including examples of potential error responses..
wire View the Possible Responses section in Send a Wire for additional documentation regarding wire responses, including examples of potential error responses..
pull View the Possible Responses section in Pull from Card for additional documentation regarding pull from card responses, including examples of potential error responses..
push View the Possible Responses section in Push to Card for additional documentation regarding push from card responses, including examples of potential error responses..

Back to Top

Additional Actions Available to Unified Card Payments Transactions

Endpoint Action Type of Transfer
/transfer-to/ach/query Query up to 20 ACH transfers ach
/transfer-to/ach/list List ACH transfers by specified search criteria ach
/transfer-to/ach/return-rates Retrieve the Return Rates Report for a specified date ach
/transfer-to/wire/query Query up to 20 wire transfers wire
/transfer-to/wire/list List wire transfers by specified search criteria wire
/transfer-to/card/get/:cardId Get the details of a registered card N/A
/transfer-to/card/transactions-query Query details of up to 20 push/pull transactions pull or push
/transfer-to/card/list/transactions List push/pull transactions by specified search criteria pull or push
/transfer-to/card/reversal Reverse a specified pull transaction pull

Back to Top

Possible Status Values

Type of Transfer Additional documentation for possible status values
ach Possible ACH Status Values.
wire Possible Wire Transfer Status Values.
pull/push Possible Pull from Card/Push to Card Status Values.

Back to Top

Webhooks

Type of Transfer Additional documentation for webhooks
ach ACH Webhooks
wire Wires Webhooks
pull/push Webhooks are not applicable for pull from card or push to card services

Back to Top