Skip to content

List Payments

Request URL

POST /public/merchant/payment/list

Description

After authenticating the merchant through your existing front-end merchant portal UI and requesting a merchant JSON Web Token through the `/payment-link/merchant/get-token` endpoint, you may make a call to this endpoint in order to allow the merchant corresponding to the provided 'x-connectfi-jwtoken' header to list their own payment link objects that match the specified properties. This action can also be facilitated through the Payment Link Iframe script when embedded into your existing front-end merchant portal UI.

Schema

Property table for public/merchant/payment/list

Property Description Required Schema
cFiTransactionId The transaction ID in the connectFi system No {
  "type": "string",
  "pattern": "^[0-9a-zA-Z_]+$",
  "minLength": 1,
  "maxLength": 36,
  "$id": "common-id"
}
cFiTransactionIds Array of transaction IDs from the connectFi system obtained when each transaction was initialized No array of {
  "type": "string"
}
status Status No {
  "type": "string",
  "nullable": true,
  "enum": [ "Initiated", "Sent", "Cancelled",
"Rejected", "Error", "Expired", "Processing",
"SentToPay", "Completed", "Settled",
"Returned", "Declined" ]
}
payerName Name of the payer No {
  "type": "string",
  "nullable": true
}
dateCreateFrom A beginning date in ISO Date format No {
  "type": "string",
  "nullable": true,
  "format": "dateISO"
}
dateCreateTo An ending date in ISO Date format No {
  "type": "string",
  "nullable": true,
  "format": "dateISO"
}
dueDateFrom A beginning date in ISO Date format No {
  "type": "string",
  "nullable": true,
  "format": "dateISO"
}
dueDateTo An ending date in ISO Date format No {
  "type": "string",
  "nullable": true,
  "format": "dateISO"
}
invoiceNumber The invoice number No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 50,
  "nullable": true,
  "$id": "common-commonStr50"
}
amountFrom A lower bound for amount No {
  "type": "number",
  "nullable": true
}
amountTo An upper bound for amount No {
  "type": "number",
  "nullable": true
}
paymentType The type of payment No {
  "type": "string",
  "nullable": true,
  "enum": [ "card", "ach" ]
}
numberOfRecords The maximum number of desired records to return No {
  "type": "number",
  "nullable": true
}
skipRecords The number of records to skip when returning results No {
  "type": "number",
  "nullable": true
}

Request Body

{
  "cFiTransactionId": "7l7TrL0ZukBQR4H4W2fsvT",
  "cFiTransactionIds": [],
  "status": "Sent",
  "dateCreateFrom": "2024-07-29T18:03:46.637Z",
  "dateCreateTo": "2024-07-30T18:03:46.637Z",
  "amountFrom": 0,
  "amountTo": 100,
  "payerName": "Doe John",
  "invoiceNumber": "11125",
  "skipRecords": 0,
  "numberOfRecords": 10
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
  "cFiTransactionId": "7l7TrL0ZukBQR4H4W2fsvT",
  "cFiTransactionIds": [],
  "status": "Sent",
  "dateCreateFrom": "2024-07-29T18:03:46.637Z",
  "dateCreateTo": "2024-07-30T18:03:46.637Z",
  "amountFrom": 0,
  "amountTo": 100,
  "payerName": "Doe John",
  "invoiceNumber": "11125",
  "skipRecords": 0,
  "numberOfRecords": 10
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/public/merchant/payment/list',
  headers: {
    'Content-Type': "application/json",
    'x-connectfi-jwtoken': "A long random string token received from /payment-link/merchant/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/public/merchant/payment/list" --data "{  \"cFiTransactionId\":\"7l7TrL0ZukBQR4H4W2fsvT\", \"cFiTransactionIds\":[], \"status\":\"Sent\", \"dateCreateFrom\":\"2024-07-29T18:03:46.637Z\", \"dateCreateTo\":\"2024-07-30T18:03:46.637Z\", \"amountFrom\":0, \"amountTo\":100, \"payerName\":\"Doe John\", \"invoiceNumber\":\"11125\", \"skipRecords\":0, \"numberOfRecords\":10}" --header "Content-Type: application/json" --header "x-connectfi-jwtoken: A long random string token received from /payment-link/merchant/get-token request" 

Successful Response Examples

200 SUCCESSFUL RESPONSE

HEADERS

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

REQUEST BODY

{
  "cFiTransactionId": "7l7TrL0ZukBQR4H4W2fsvT",
  "cFiTransactionIds": [],
  "status": "Sent",
  "dateCreateFrom": "2024-07-29T18:03:46.637Z",
  "dateCreateTo": "2024-07-30T18:03:46.637Z",
  "amountFrom": 0,
  "amountTo": 100,
  "payerName": "Doe John",
  "invoiceNumber": "11125",
  "skipRecords": 0,
  "numberOfRecords": 10
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "total": {
            "skipRecords": 0,
            "numberOfRecords": 1,
            "more": false
        },
        "items": [
            {
                "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": "Sent",
                "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": "customer_email@email.test"
                    },
                    {
                        "index": 4,
                        "code": "phone",
                        "label": "Phone",
                        "value": "15555555555"
                    }
                ],
                "availablePaymentType": [
                    "card",
                    "ach"
                ],
                "statusChangeHistory": [
                    {
                        "initiatorId": "2Bc0QW0VYJe7VhTyXXEYNQ",
                        "initiatorType": "merchant",
                        "status": "Initiated",
                        "_id": "66a9292032bc537c4b70dc31",
                        "dtsCreatedAt": "2024-07-30T17:55:44.024Z",
                        "dtsUpdatedAt": "2024-07-30T17:55:44.024Z"
                    },
                    {
                        "initiatorId": "2Bc0QW0VYJe7VhTyXXEYNQ",
                        "initiatorType": "merchant",
                        "status": "Sent",
                        "_id": "66a9295d32bc537c4b70dc39",
                        "dtsCreatedAt": "2024-07-30T17:56:45.190Z",
                        "dtsUpdatedAt": "2024-07-30T17:56:45.190Z"
                    }
                ],
                "dtsCreatedAt": "2024-07-30T17:55:44.024Z",
                "link": "3zjGoeyuHi1bPgCNgb2B1JERhfzLWU0SogPsgBG0nbb3d4RAHH2APVeyqldsOiH8C",
                "url": "google.com/payment/3zjGoeyuHi1bPgCNgb2B1JERhfzLWU0SogPsgBG0nbb3d4RAHH2APVeyqldsOiH8C"
            }
        ]
    },
    "requestId": "5685bfe04e9e11ef92543a54d404e711"
}

200 SUCCESSFUL RESPONSE - NO MATCHES

HEADERS

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

REQUEST BODY

{
  "status": "Initiated"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "total": {
            "skipRecords": 0,
            "numberOfRecords": 0,
            "more": false
        },
        "items": []
    },
    "requestId": "3b7d8760541a11efb9c8eca582d34911"
}