Currently, there're already 2 configurable fields: merchant and description. There's no longer a notes field. Are these 2 fields sufficient?

In order to import and process a transaction, the general rule is more = better. Even when it's nullable, you basically offload the problem to me.

1. Bank account numbers, credit card numbers and IBANs are generally unique, as opposed to names. So, merchant should be accompanied by merchant_iban or something like that. That makes it easier to match records without keeping track of all combinations.
2. Strictly speaking it should be something like opposing_party or payee because the "merchant" could also be your own savings account.
3. Notes and descriptions are often used interchangeably. Since your USP is that you offer this customization in the first place, you could always consider offering even more of these fields that users can fill as they please: merchant, notes, description, designation, etc.
4. I think Spectre / Salt Edge offers the "extra" array, where it puts everything it doesn't have a place for. The array is entirely optional, often empty, and no guarantees what may end up there. That may be a way for you as well to offload the parsing do the user, without withholding data from them.

Excellent feedback, thank you very much for sharing!

1. Bank account numbers, credit card numbers and IBANs are generally unique, as opposed to names. So, merchant should be accompanied by merchant_iban or something like that. That makes it easier to match records without keeping track of all combinations.

I see your point. This is why the mapping is available, so you can add as many relevant fields as you need, or do you see any other outstanding issues there even with the mapping in place.

Strictly speaking it should be something like opposing_party or payee because the "merchant" could also be your own savings account.

That makes complete sense. I like payee, but didn't see it used often in many of the APIs I reviewed during design. Given this would be a breaking change, will likely plan it as part of other API changes, but definetly open to changing this.

Notes and descriptions are often used interchangeably. Since your USP is that you offer this customization in the first place, you could always consider offering even more of these fields that users can fill as they please: merchant, notes, description, designation, etc.

Another good idea, will keep that mind.

I think Spectre / Salt Edge offers the "extra" array, where it puts everything it doesn't have a place for. The array is entirely optional, often empty, and no guarantees what may end up there. That may be a way for you as well to offload the parsing do the user, without withholding data from them.

Interesting. Another idea I have been thinking of is embedding an optional object for each provider that matches their schema.

raw: {
  goCardless: {
     iBan: '..'
  },
  mx: {
     extraDetails: '...'
  }
}

I like that this allows me to offer a familiar schema, and at the same time, I can document it easily. Thoughts?

I see your point. This is why the mapping is available, so you can add as many relevant fields as you need, or do you see any other outstanding issues there even with the mapping in place.

The only issue I see is that 2 fields (merchant and description) isn't enough fields. Because in my case, I really need the merchant to be present and it must be the opposing party. So there is really only 1 field left to do customization on.

I would not recommend that users also can set the keys. If you allow users to customize the keys as well (for example, the user may add a custom field my_custom_field with custom content), I would also have to explain them that Firefly III actually expects custom_ff3_field or something like that. OR possibly, there must be another endpoint where I can download for each user their custom mapping, so I can see what fields I have to read. This adds a lot of complicated code, and I doubt that many users will need this.

I like that this allows me to offer a familiar schema, and at the same time, I can document it easily. Thoughts?

Yes I like that.

I see your point. This is why the mapping is available, so you can add as many relevant fields as you need, or do you see any other outstanding issues there even with the mapping in place.

The only issue I see is that 2 fields (merchant and description) isn't enough fields. Because in my case, I really need the merchant to be present and it must be the opposing party. So there is really only 1 field left to do customization on.

I would not recommend that users also can set the keys. If you allow users to customize the keys as well (for example, the user may add a custom field my_custom_field with custom content), I would also have to explain them that Firefly III actually expects custom_ff3_field or something like that. OR possibly, there must be another endpoint where I can download for each user their custom mapping, so I can see what fields I have to read. This adds a lot of complicated code, and I doubt that many users will need this.

How about using the templates to concatenate multiple fields into the description field? there're examples of this on the configuration page:

You could even make it a JSON object and use the values from there.