Guides

Payment Instruments

A Payment Instrument represents the means by which funds are transferred from one party to another.
Currently, Sharable Cash supports "Bank account" as a Payment Instrument.
The Payment instrument may be of two types:
Funding
Withdrawal

The Payment Instrument form has the following fields:

Field Name	Length/Format	Validation	Required: yes/no
`payment_instrument_tags.key`	length: 3-50	Digits, letters, and special characters: `!@.-_#`	Yes
`payment_instrument_tags.value`	length: 3-50	Digits, letters, and special characters: `!@.-_#`	Yes
`payment_instrument_id`	Predefined in the dictionary: GET /dictionaries/payment-instrument-types	Digits	Yes
`payment_method_id`	Predefined in the dictionary: GET /dictionaries/payment-methods	Digits	Yes
`is_default`	true/false		Yes
`payment_instrument_label`	length: 1-256 characters	Any symbols	Yes
`payment_instrument_change_reason`	length: 1-256 characters	Any symbols	Yes
`account_number`	length: 4-17 characters	Digits	Yes
`routing_number`	length: 9 characters	Digits	Yes
`payment_instrument_ach_type_id`	Predefined in the dictionary: GET /dictionaries/payment-instrument-ach-types	Digits	Yes

Create a Payment Instrument for a Customer Profile

Before creating a Payment Instrument for a Customer, a Facilitator should know the customer_profile_id and a program_id. To get a Customer Profile information check how to create a Customer Profile.

To create a Payment Instrument for a Customer Profile, follow the next steps:

1. Get a program_id:

GET /programs

//Sample response (the list is limited for demonstration purposes)

{
  "paging": {
    "page_size": 50,
    "page_number": 1,
    "total_count": 3,
    "last_evaluated_key": null
  },
  "data": [
    {
      "program_id": "prm_gffshiRdalN7Iabc",
      "program_name": "VSETest new",
      "program_description": "VSE Test direct sharing program.",
      "program_display_name": "VSETest new",
      "created_by": "SYSTEM",
      "created_date_time": "2023-03-02T16:09:00",
      "modified_by": "SYSTEM",
      "modified_date_time": "2023-03-02T16:09:00"
    }
   
  ],
  "errors": null
}

2. If Customer’s Profile is not connected to the Program, this can be done by the following request:

POST /programs/{program_id}/customer-profiles

You should specify customer_profile_id in the request body, to connect a specific Customer to the Program and specify the reason for attaching the Customer to the Program. Check details at Add Customer Profile to Program.

2.1. If a Customer is already connected to the Program, you’ll get the following response when executing:

POST /programs/{program_id}/customer-profiles

//Sample response


{
 "paging": null,
 "data": null,
 "errors": [
   {
     "code": 21001,
     "message": "Customer Profile already attached to the program"
   }
 ]
}

2.2. You may verify whether a Customer is already attached to the Program by checking:

GET /programs/{program_id}/customer-profiles/{customer_profile_id}

//Sample response if a Customer is connected to a Program

{
  "paging": null,
  "data": [
    {
      "customer_profile_id": "csp_Jc8zaB1daD4oyeWl",
      "program_id": "prm_gffsdiRdalN7Ixyo",
      "customer_profile_program_status_id": 10,
      "customer_profile_program_status_reason": "Attached at a Customer's request",
      "is_locked": false,
      "created_by": "510E7392ED8E4149",
      "created_date_time": "2023-05-08T13:06:06.953",
      "modified_by": "510E7392ED8E4149",
      "modified_date_time": "2023-05-08T13:06:06.953"
    }
  ],
  "errors": null
}

//Sample response if a Customer is NOT connected to Program

{
 "paging": null,
 "data": null,
 "errors": [
   {
     "code": 10001,
     "message": "Invalid Value"
   }
 ]
}

3. Get Payment Instrument Type:

GET /dictionaries/payment-instrument-types

Payment Instruments can be of Funding or Withdrawal type. Based on the type, a specific Payment Instrument will be selected when creating a Tranaction.

//Sample response

{
  "paging": {
    "page_size": 50,
    "page_number": 1,
    "total_count": 2,
    "last_evaluated_key": null
  },
  "data": [
    {
      "payment_instrument_type_id": 1,
      "payment_instrument_type_name": "Funding",
      "payment_instrument_type_display_name": "Funding",
      "payment_instrument_type_description": "Used in funding transfers."
    },
    {
      "payment_instrument_type_id": 2,
      "payment_instrument_type_name": "Withdrawal",
      "payment_instrument_type_display_name": "Withdrawal",
      "payment_instrument_type_description": "Used in withdrawal transfers."
    }
  ],
  "errors": null
}

4. Get a Payment Method:

GET /dictionaries/payment-methods

{
  "paging": {
    "page_size": 50,
    "page_number": 1,
    "total_count": 2,
    "last_evaluated_key": null
  },
  "data": [
    {
      "payment_method_id": 1,
      "payment_method_name": "Ach",
      "payment_method_display_name": "ACH",
      "payment_method_description": "Automated Clearing House."
    }
  ],
  "errors": null
}

Currently, only the ACH Payment method is supported, so your payment_method_id is 1.

5. Get Payment Instrument ACH Type:

GET/dictionaries/payment-instrument-ach-types

The ACH Payment Instrument can be of the following types:
Saving
Checking

//Sample response


{
  "paging": {
    "page_size": 50,
    "page_number": 1,
    "total_count": 2,
    "last_evaluated_key": null
  },
  "data": [
    {
      "payment_instrument_ach_type_id": 1,
      "payment_instrument_ach_type_name": "Savings",
      "payment_instrument_ach_type_display_name": "Savings",
      "payment_instrument_ach_type_description": "Savings."
    },
    {
      "payment_instrument_ach_type_id": 2,
      "payment_instrument_ach_type_name": "Checking",
      "payment_instrument_ach_type_display_name": "Checking",
      "payment_instrument_ach_type_description": "Checking."
    }
  ],
  "errors": null
}

6. Create a Payment Instrument:

POST /customer-profiles/{customer_profile_id}/payment_instruments

//Sample request

{
 "payment_instrument_tags": [
   {
     "key": "Priority",
     "value": "High"
   }
 ],
 "payment_instrument_type_id": 1,
 "payment_method_id": 1,
 "is_default": true,
 "payment_instrument_label": "ACH payment",
 "payment_instrument_change_reason": "Payment Instrument created.",
 "program_id": "prm_gffsdiRdalN7Ixyo",
 "payment_instrument_ach": {
   "account_number": "0000000022",
   "routing_number": "122105278",
   "payment_instrument_ach_type_id": 1
 }
}

//Sample response

{
 "paging": null,
 "data": [
   {
     "id": "pin_EdE35xvDSpSdPCC5"
   }
 ],
 "errors": null
}

As a result you get an id of the Payment Instrument.
The Payment Instrument can be set as default; to do so, set "is_default": true.
The payment_instrument_tags.key should be unique.

5. If you want to check all the Payment Instruments added to a Customer, use the following request:

GET /customer-profiles/{customer_profile_id}/payment-instruments

//Sample response


{
 "paging": {
   "page_size": 50,
   "page_number": 1,
   "total_count": 1,
   "last_evaluated_key": null
 },
 "data": [
   {
     "payment_instrument_id": "pin_EdE35xvDSpSdPCC5",
     "payment_instrument_tags": [
       {
         "key": "Prioruty",
         "value": "Low"
       }
     ],
     "payment_instrument_status_id": 40,
     "payment_instrument_type_id": 1,
     "payment_method_id": 1,
     "is_default": true,
     "is_locked": false,
     "payment_instrument_change_reason": "Payment Instrument created.",
     "payment_instrument_ach": {
       "account_number": "0022",
       "routing_number": "5278",
       "payment_instrument_ach_type_id": 1
     },
     "created_by": "1468B74AE4566CCB",
     "created_datetime": "2023-05-08T15:28:49.413",
     "modified_by": "66671AF487F9B213",
     "modified_datetime": "2023-05-08T15:30:54.03"
   }
 ],
 "errors": null
}

6. To check the status of just created Payment Instrument:

GET /customer-profiles/{customer_profile_id}/payment-instruments/{payment_instrument_id}

//Sample response


{
 "paging": null,
 "data": [
   {
     "payment_instrument_id": "pin_EdE35xvDSpSdPCC5",
     "payment_instrument_tags": [
       {
         "key": "4562120",
         "value": "1353520"
       }
     ],
     "payment_instrument_status_id": 40,
     "payment_instrument_type_id": 1,
     "payment_method_id": 1,
     "is_default": true,
     "is_locked": false,
     "payment_instrument_change_reason": "Payment Instrument created.",
     "payment_instrument_ach": {
       "account_number": "0022",
       "routing_number": "5278",
       "payment_instrument_ach_type_id": 1
     },
     "created_by": "1468B74AE4566CCB",
     "created_datetime": "2023-05-08T15:28:49.413",
     "modified_by": "66671AF487F9B213",
     "modified_datetime": "2023-05-08T15:30:54.03"
   }
 ],
 "errors": null
}

Update a Payment Instrument for a Customer Profile

You can update only the payment_instrument_label, the payment_instrument_change_reason, and whether this instrument should be the default.

1. To update a Payment Instrument, use the following request:

PUT/customer-profiles/{customer_profile_id}/payment-instruments/{payment_instrument_id}

//Sample request


{
 "is_default": true,
 "payment_instrument_label": "My secondary bank",
 "payment_instrument_change_reason": "Changing at a Customer's request"
}

//Sample response

{
 "paging": null,
 "data": [
   {
     "id": "pin_EdE35xvDSpSdPCC5"
   }
 ],
 "errors": null
}