fiatconnect / specification

FiatConnect API Specification
28 stars 21 forks source link

feat(transfers): Add support for user-initiated transfers in #97

Closed jophish closed 1 year ago

jophish commented 1 year ago

Formalizes the discussion present in #93.

This PR adds formal support to the FiatConnect specification for user-initiated transfers in.

At a high level, this is accomplished by introducing two new (capital 'C') concepts to the FiatConnect specification: User Action Type and User Action Details.

At the time of getting a quote from POST /quote/in, if a particular Fiat Account schema will require user action to send fiat funds to the provider, a User Action Type should be specified alongside that schema in the quote response. When initiating the transfer by calling POST /transfer/in, if the fiat account being used for that transfer has a schema that was designated as requiring user action by the quote, the POST /transfer/in response will contain User Action Details, containing information required by the user in order to complete the action needed to progress the transfer. Each User Action Type has a corresponding User Action Details schema, each with different semantics.

I've included initial User Action Type/User Action Details support for PIX, IBAN, and PSE. Let me know if I'm missing something that you'll immediately need support for; I don't want to bloat this PR with support for User Action Types/User Action Details that won't be immediately needed; those can always be added easily in a follow-on PR.

As a consequence of these new concepts, this PR also adds in a new transfer state, as well as adding additional fields to transfer status details both in the API itself, and in webhook payloads.

cajubelt commented 1 year ago

i'm curious if there are some fiat account types where the provider doesn't actually need to know any information about the user's fiat account before a user-initiated fiat transfer takes place. For instance, for PSE do they actually need the account number for the originating account first?