Skip to content

Card Payment

Request URL

POST /public/customer/payment/card-pay

Description

This endpoint* will allow the customer session corresponding to the provided 'x-connectfi-jwtoken' header to complete a card payment using the specified card details. This action can also be facilitated through the payment page HTML that is provided when the customer payment link email is sent or, depending on client configurations, the payment link webhook.

A successful submission will register the card in connectFi and execute a funds pull from the card for the payment amount.

The sensitive card details are not stored in connectFi and must be tokenized before the card can be registered or used to pull funds. For more information on tokenization of card data see Getting Started > Tokenization.

  • Payment Link payments via card are coming soon

Schema

Property table for public/customer/payment/card-pay

Property Description Required Schema
clearCard An object containing unencrypted card details Yes clearCard object
owner An object containing owner details Yes toucan owner object

Property table for toucan owner object

Property Description Required Schema
address Address details Yes toucan address object
name Name Yes toucan cardHolderName object
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 cardHolderName object

Property Description Required Schema
first First name Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
last Last name Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
middle Middle name No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 50,
  "nullable": true,
  "$id": "common-commonStr50"
}
suffix Suffix No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 50,
  "nullable": true,
  "$id": "common-commonStr50"
}

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"
}

Property table for clearCard object

Property Description Required Schema
accountNumber The account number Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
expirationDate The expiration date Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
securityCode The CVV security code Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}

Request Body

{
  "clearCard": {
    "accountNumber": "1234567890123456",
    "expirationDate": "202612",
    "securityCode": "123"
  },
  "owner": {
    "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": "5556667777"
    }
  }
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
  "clearCard": {
    "accountNumber": "1234567890123456",
    "expirationDate": "202612",
    "securityCode": "123"
  },
  "owner": {
    "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": "5556667777"
    }
  }
}
;
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/public/customer/payment/card-pay',
  headers: {
    'Content-Type': "application/json",
    'x-connectfi-jwtoken': "A long random string token received from /public/customer/payment/link 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/public/customer/payment/card-pay" --data "{  \"clearCard\":{    \"accountNumber\":\"1234567890123456\",   \"expirationDate\":\"202612\",   \"securityCode\":\"123\"  }, \"owner\":{    \"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\":\"5556667777\"    }  }}" --header "Content-Type: application/json" --header "x-connectfi-jwtoken: A long random string token received from /public/customer/payment/link request"

Successful Response Examples

200 SUCCESSFUL RESPONSE

HEADERS

Header Value
Content-Type application/json
x-connectfi-jwtoken A long random string token received from /public/customer/payment/link request

REQUEST BODY

{
  "clearCard": {
    "accountNumber": "1234567890123456",
    "expirationDate": "202612",
    "securityCode": "123"
  },
  "owner": {
    "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": "5556667777"
    }
  }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiTransactionId": "7l7TrL0ZukBQR4H4W2fsvT",
        "cFiAggregatorId": "CLIENTID",
        "cFiMerchantId": "2Bc0QW0VYJe7VhTyXXEYNQ",
        "payerName": "Doe John",
        "cFiMerchantRef": "1",
        "invoiceNumber": "11125",
        "amount": 1.5,
        "currency": "USD",
        "dtsExpiredAt": "2024-08-29T17:56:45.189Z",
        "dueDate": "2024-08-29",
        "description": "test description",            
        "status": "Settled",
        "fields": [
            {
                "index": 1,
                "code": "firstName",
                "label": "First Name",
                "value": "John"
            },
            {
                "index": 2,
                "code": "lastName",
                "label": "Last Name",
                "value": "Doe"
            },
            {
                "index": 3,
                "code": "email",
                "label": "Email",
                "value": "c*********************@e****.test"
            }
        ],
        "availablePaymentType": [
            "ach",
            "card"
        ],
        "statusChangeHistory": [
            {
                "initiatorId": "2Bc0QW0VYJe7VhTyXXEYNQ",
                "initiatorType": "merchant",
                "status": "Initiated",
                "dtsCreatedAt": "2024-07-30T17:55:44.024Z",
                "dtsUpdatedAt": "2024-07-30T17:55:44.024Z"
            },
            {
                "initiatorId": "2Bc0QW0VYJe7VhTyXXEYNQ",
                "initiatorType": "merchant",
                "status": "Sent",
                "dtsCreatedAt": "2024-07-30T17:56:45.190Z",
                "dtsUpdatedAt": "2024-07-30T17:56:45.190Z"
            },
            {
                "initiatorType": "public",
                "status": "SentToPay",
                "dtsCreatedAt": "2024-08-02T12:35:12.953Z",
                "dtsUpdatedAt": "2024-08-02T12:35:12.953Z"
            },
            {
                "initiatorType": "public",
                "status": "Settled",
                "dtsCreatedAt": "2024-08-02T12:35:14.404Z",
                "dtsUpdatedAt": "2024-08-02T12:35:14.404Z"
            }
        ],
        "dtsCreatedAt": "2024-07-30T17:55:44.024Z",
        "link": "3zjGoeyuHi1bPgCNgb2B1JERhfzLWU0SogPsgBG0nbb3d4RAHH2APVeyqldsOiH8C",
        "url": "google.com/payment/3zjGoeyuHi1bPgCNgb2B1JERhfzLWU0SogPsgBG0nbb3d4RAHH2APVeyqldsOiH8C",
        "paymentType": "card"
    },
    "requestId": "a8ce4bd050cb11efb9c8eca582d34911"
}