Excel payment instructions FSP - global-121/121-platform GitHub Wiki

This manual generic FSP can be used when no API-FSP integration is available for a program.

• When initiating a payment with a non-api FSP no payment instructions will be sent directly to the FSP yet.
• Instead, the portal-user must export the payment instructions by selecting the right payment from the dropdown list in the payment page and pressing 'Export FSP instructions'.
• This particular manual generic FSP is called 'Excel' (use this name e.g. in imports) and shows as 'Excel Payment Instructions' in the portal.

Export FSP Instructions

• You can configure which columns are included in the export in 2 ways:

  • at program setup, by specifying columnsToExport in the initial program-json

  "financialServiceProviders": [
     {
       "fsp": "Excel",
       "configuration": [
         {
           "name": "columnsToExport",
           "value": ["name", "birthdate", "documentid"]
         }
       ]
     }
    ]
  

  • later by creating or updating a program-fsp-configuration using either POST /api/programs/{programId}/fsp-configuration or PUT /api/programs/{programId}/fsp-configuration/{programFspConfigurationId}.

  {
     "fspId": 15,
     "name": "columnsToExport",
     "value": "[\"name\",\"phoneNumber\"]"
  }
  

• columnsToExport must be an array of strings, where the array-elements can be any program-questions, program-custom-attributes or root-level registration attributes (e.g. paymentAmountMultiplier).

• There is only validation on whether the supplied value is a string or an array of strings, but not specifically if in the case of name=columnsToExport it is an array of strings, which it should be.

• There is also no validation on whether the array-elements are known attributes. If it contains unrecognized elements, these will simply be ignored in the export.

• Lastly, if no columnsToExport is specified, then all program-questions and program-custom-attributes will be exported, but no root-level registration attributes.

Import FSP Reconciliation data

• Initially the transactions from a payment with this FSP will have status 'waiting'.
• You can update transaction statuses to 'success' or 'error' by selecting a payment in the Payment page and pressing 'Import Payment Reconciliation Data'.
• Beforehand specify on which column the uploaded data must be matched to the 121 registration data:
  • at program setup, by specifying columnToMatch in the initial program-json

    "financialServiceProviders": [
       {
         "fsp": "Excel",
         "configuration": [
           {
             "name": "columnsToExport",
             "value": ["name", "birthdate", "documentid"]
           },
           {
             "name": "columnToMatch",
             "value": "documentid"
           }
         ]
       }
    ]
    

  • later by creating or updating a program-fsp-configuration using either POST /api/programs/{programId}/fsp-configuration or PUT /api/programs/{programId}/fsp-configuration/{programFspConfigurationId}.
  • columnToMatch must be a string, and can be any registration root-level attribute (e.g. "phoneNumber") or program-question or program-custom-attribute.
  • Note that no validation on the existence of columnToMatch is done. If not recognized, then simply no records will be matched.
• The import-file
  • must be of CSV-format.
  • The file must contain a column status, which is failed with values success or error. If no such column, or other values, an error will be thrown.
  • Maximum 10k records per upload are allowed. If there are more PAs included in a payment, the file must be split up and uploaded separately.
• Edge cases
  • If the file contains multiple records with the same value for columnToMatch then the later record will simply overwrite the earlier.
  • If there are multiple registrations with the same value for columnToMatch in the database, then the first matching registration (in no particular order) will be used to update the transaction of.