eCommerce P2M Payments: DIP-158 #166
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Disclaimer regarding the discovery phase Extended scope for fund pull pre-approval Revoke an authorization in more details
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Disclaimer regarding the discovery phase Extended scope for fund pull pre-approval Revoke an authorization in more details
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
Co-authored-by: kphfb <kph@fb.com>
dimroc
reviewed
Apr 28, 2021
There was a problem hiding this comment.
Comments inline. At a high level,
- I would second @davidiw's comment to explicitly capture when we perform attestation.
- An overarching theme I would like to discuss tomorrow is the assumption that we have transaction data (name, address) for every P2M flow.
- Do we need to capture the notion of a payment timing out even outside of the auth/capture flow? ie: an approved charge that doesn't settle until a month later.
dips/dip-158.md
Outdated
Comment on lines
125
to
138
| The following values are added to the status enum of [PaymentActor](https://dip.diem.com/dip-1/#paymentactorobject) object: | ||
|
|
||
| * `authorized` - This means the actor has performed all required tasks and funds are locked for a future capture. Note that the actual lock is done by the wallet (sender), so for the receiver this status means that all risk checks were successful and it is willing to accept the payment. | ||
| * `needs_init_data` - This means the actor requires basic data to initialize the payment. For the receiver, this status means that the payer data is required. For the sender, it means that the merchant data is required | ||
|
|
||
| For completeness purposes, the full list of values is: | ||
| * `none` | ||
| * `needs_kyc_data` | ||
| * `ready_for_settlement` | ||
| * `abort` | ||
| * `authorized` | ||
| * `soft_match` | ||
| * `needs_init_data` | ||
|
|
There was a problem hiding this comment.
authorized was also suggested in DIP 8 so I recognize the reuse here.
nit: needs_init_data I pair with the notion of a step up, when a VASP requests additional information. This could be the case for a VASP even if they receive name and address, depending on configuration, and later on in the flow's lifecycle. Step ups, or asking for more info, is common in the PSP/payment processing space. I don't feel that we have to tie it to the init phase. I would suggest a simple rename of needs_data.
dips/dip-158.md
Outdated
| | action | enum | Y | Populated in the request. This value indicates the requested action to perform. For immediate capture and P2P transfer, "charge" is used. For auth and capture, "auth" and "capture" are now available. "capture" can only be performed after a valid "auth" | | ||
| | valid_until | uint | N | Unix timestamp indicating until when the payment can be authorized. Once this time has been reached, the payment cannot be authorized and funds cannot be locked. | | ||
| | timestamp | uint | Y | Unix timestamp indicating the time that the payment Command was created. | ||
| | |
There was a problem hiding this comment.
When properly rendered, there are a lot of dangling |. You don't want a newline before closing the above row.
High level feedback summarySome of this is redundant to previous comments, consolidating here for readability.
|
davidiw
reviewed
Apr 28, 2021
dips/dip-158.md
Outdated
Comment on lines
125
to
138
| The following values are added to the status enum of [PaymentActor](https://dip.diem.com/dip-1/#paymentactorobject) object: | ||
|
|
||
| * `authorized` - This means the actor has performed all required tasks and funds are locked for a future capture. Note that the actual lock is done by the wallet (sender), so for the receiver this status means that all risk checks were successful and it is willing to accept the payment. | ||
| * `needs_init_data` - This means the actor requires basic data to initialize the payment. For the receiver, this status means that the payer data is required. For the sender, it means that the merchant data is required | ||
|
|
||
| For completeness purposes, the full list of values is: | ||
| * `none` | ||
| * `needs_kyc_data` | ||
| * `ready_for_settlement` | ||
| * `abort` | ||
| * `authorized` | ||
| * `soft_match` | ||
| * `needs_init_data` | ||
|
|
There was a problem hiding this comment.
This is a good reason to just strip out this data structure from this exchange and use a dedicated customer and merchant (business) data structure that contains nothing more than name, address, and phone number (and maybe additional valuable, identifying fields)
Notes: Agreed that we will create new structures for P2M purposes rather than impose changes on existing structures from 0 < DIP < 2 (did not want to use the actual DIP name :)). For example, we will NOT extend or change the PaymentActorObject. Instead, we will create a new object suitable for P2M needs (e.g. BusinessActorObject). Agreed that business_data (i.e. merchant basic details) should be part of the InfoCommand response Agreed that payer_data (i.e. payer information) should be part of the InitCommand(s) request Agreed that, for the time being, there is no support for an additional step to ask for more data. The receiving VASP can either accept or reject the payment based on the information provided. We mentioned that the receiving VASP should be able to state "extra" information that is required on top of the payer_data (e.g. DOB might be required for buying alcohol) as part of the InfoCommand response. This will be achieved by an additional optional element (type will be JSON) A similar optional element will be added to the InitCommand(s) request. This element is to be used by the sending VASP to send the additional information requested (e.g. DOB) Agreed (with a heavy heart...) to stop using the functionality names and stick with the command types Agreed to use two different init command types (for each payment type) to replace the single InitCommand We will change the name of the ReadyCommand to be ReadyNotification Add dual attestation specification for transactions over the limit
dimroc
suggested changes
Apr 29, 2021
dips/dip-8.md
Outdated
|
|
||
| For the sake of simplicity, we use the following terms: | ||
| * "Buyer VASP" - The VASP who submits payment transactions to the blockchain in order to pay to the other VASP | ||
| * "Merchant" - The VASP who recieves the funds (transaction) |
There was a problem hiding this comment.
Can we explicitly say Merchant VASP as we have other docs that have a lot of communication between Merchant and Merchant VASP.
dips/dip-8.md
Outdated
| --- | ||
|
|
||
| For the sake of simplicity, we use the following terms: | ||
| * "Buyer VASP" - The VASP who submits payment transactions to the blockchain in order to pay to the other VASP |
There was a problem hiding this comment.
We use Customer VASP in other DIPs, can we be consistent?
dips/dip-8.md
Outdated
|
|
||
| | Field | Type | Required? | Description | | ||
| |------------------------|---------|------------|------------------------------------------------| | ||
| | vasp_address | str | Y | Address of account from which billing will happen. The address is encoded using bech32 and should uniquly identify the merchant. For Diem addresses format, refer to the "account identifiers" section in [DIP-5](https://dip.diem.com/dip-5/#account-identifiers). | |
dips/dip-8.md
Outdated
| |------------------------|---------|------------|------------------------------------------------| | ||
| | vasp_address | str | Y | Address of account from which billing will happen. The address is encoded using bech32 and should uniquly identify the merchant. For Diem addresses format, refer to the "account identifiers" section in [DIP-5](https://dip.diem.com/dip-5/#account-identifiers). | | ||
| | funds_pull_pre_approval_id | str | Y | A unique identifier of this pre-approval. Should be a UUID according to RFC4122 with "-"'s included. | | ||
| | merchant_name | str | Y | The name of the biller | |
There was a problem hiding this comment.
I like the use of merchant here. Compared to DIP 158 however, our naming seems inconsistent. In DIP 158 we're hesitant to be narrow and tight in our definitions, and use "payment receiver" and the like. It would be great to be consistent.
On that note, should this object be a PaymentReceiverObject? Seems like no if entirely sent over URL.
|
Agree.
Not sure why DIP 8 appears in the pull request. Please ignore it.
Yinon
…On Thu, Apr 29, 2021, 19:17 Dimitri Roche ***@***.***> wrote:
***@***.**** requested changes on this pull request.
Went ahead and did a first pass. I do think DIP 158 and the changes to DIP
8 would have an easier review process and lifecycle if in separate PRs.
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> + },
+ "action": {
+ PaymentActionObject()
+ },
+ "reference_id": "4185027f-0574-6f55-2668-3a38fdb5de98",
+ "description": "payment request description"
+}
+```
+
+## PaymentReceiverObject
+A PaymentReceiverObject represents the business/merchant in the payment. In P2M scenarios it is the receiver of funds.
+
+|Field|Type|Required?|Description|
+|-|-|-|-|
+| address | str | Y | Address of the receiver account. The addresses are encoded using bech32|
+|business_data|[BusinessDataObject](#businessdataobject)|Y|It includes the details of the merchant to be displayed to the payer|
nit: Is it standard in our DIPs to have address interchangeably used to
mean receiver accounts or physical address? If so, that's a shame.
Otherwise, let's disambiguate it and have physical_address or some other
name to prevent misuse.
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> +
+Successful authorization will not necessarily be followed by a successful capture. It is possible that the receiver will choose to cancel the authorization and essentially void the payment before it was captured. One possible reason to void a payment is that the products for which an amount was locked are out of stock and cannot be fulfilled.
+
+---
+## New Structures
+---
+This section introduces new structures required for P2M scenarios.
+## PaymentInfoObject
+The minimal payment details required in order for the payer to decide whether the accept the payment or reject it.
+
+Field|Type|Required?|Description|
+|-|-|-|-|
+|receiver|[PaymentReceiverObject](#paymentreceiverobject)|Y|The details of the payment receiver (e.g. merchant)|
+|action|[PaymentActionObject](#paymentactionobject)|Y|Information regarding the type of payment and payment amount|
+|reference_id|str|Y|Unique reference ID of this payment. This value should be globaly unique|
+|description|str|N|Description of the payment. To be displayed to the customer|
reach: Would we also want an optional image url either for the business or
product?
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> +"sender": {
+ "address": "dm1pg9q5zs2pg9q5zs2pg9q5zs2pg9skzctpv9skzcg9kmwta",
+ "payer_data": {
+ PayerDataObject()
+ }
+}
+```
+
+## PayerDataObject
+The details of the payer. payer_data is the minimal set of payer information required by the merchant to perform risk checks and apply AML policies.
+|Field|Type|Required?|Description|
+|-|-|-|-|
+|given_name|str|Y|Legal given name of the payer|
+|surname|str|Y|Legal surname of the payer|
+|address|AddressObject|Y|Merchant's physical address information|
+|national_id|[NationalIdObject](https://github.com/diem/dip/blob/master/dips/dip-1.mdx#nationalidobject)|N|National ID information for payer. e.g. SSN|
This optional field seems like overreach. I've never in eCommerce had to
send my social security number for an online purchase. Does this happen in
other countries? If not, let's cut it.
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> + "legal_name": "Acme Technologies Inc.",
+ "address": {
+ AddressObject()
+ }
+}
+```
+
+## PaymentActionObject
+Information about the payment type (i.e. action), amount and currency.
+
+|Field|Type|Required?|Description|
+|-----|----|---------|-----------|
+| amount | uint | Y | Amount of the transfer. Base units are the same as for on-chain transactions for this currency. For example, if DiemUSD is represented on-chain where "1" equals 1e-6 dollars, then "1" equals the same amount here. For any currency, the on-chain mapping must be used for amounts. |
+| currency | enum | Y | One of the supported on-chain currency types, e.g. XUS|
+| action | [Action enum](#action-enum) | Y | Populated in the request. This value indicates the requested action to perform. For immediate capture and P2P transfer, "charge" is used. For auth and capture, "auth" and "capture" should be used. "capture" can only be performed after a valid "auth" |
+| valid_until | uint | N | Unix timestamp indicating until when the payment can be authorized. Once this time has been reached, the payment cannot be authorized and funds cannot be locked. |
This could be required for auth, and capped at say 3 months so we don't
have an auth lingering around forever. Reference:
https://wallethub.com/answers/cc/how-long-does-a-credit-card-authorization-last-2140697276/
It seems that this object has valid_until optional to support the charge
and capture scenarios. What is supposed to happen if it's not set for auth?
Error or cap at 3 months at the discretion of the VASP?
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> + "action": "auth",
+ "valid_until": 74000,
+ "timestamp": 72322,
+}
+```
+### Action Enum
+The following values are allowed for the Action Enum
+* `charge`
+* `auth`
+* `capture`
+
+## PaymentStatusObject
+| Field | Type | Required? | Description |
+|-|-|-|-|
+| status | [(Status enum)](#status-enum) | Y | Status of the payment|
+| abort_code |[(AbortCode enum)](#abortcode-enum)| N | In the case of an `abort` status, this field may be used to describe the reason for the abort. Represents the error code of the corresponding error|
Remove parentheses around (status/abort enum)
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> +| needs_init_data | ready_for_settlement | All required tasks were performed and the payment is ready for settlement |
+| needs_init_data | authorized | All required tasks were performed and the funds are ready to be locked |
+| authorized | ready_for_settlement | Funds captured |
+| authorized | abort | Payment was voided |
+| needs_init_data | abort | Payment aborted before initial data was verified |
+| none | abort | Payment aborted before initialization |
+| ready_for_settlement | abort | One party aborted the payment even though the other party already notified it is ready to settle the payment. For example, it may happen if the sender does not approve merchant data provided by the receiver
+
+### AbortCode Enum
+* `void`- This abort code should be used for voiding a payment that was previously authorized. For example, the merchant voided the payment because the purchased products are out of stock. It is expected that the sender VASP will respond with void code as a sign of agreement
+* `risk_checks_failed`- This abort code should be used when the risk checks performed based on the payer information failed
+* `rejected` - This abort code should be used for aborting a payment not covered by other values of the enum
+
+## New Command Types
+The following is a list of new values for the `command_type` field of the `CommandRequestObject`. Each command type denotes a step in the off-chain negotiations and specifies the data of the requests and the response
+* `InfoCommand` - Allows obtianing payment information based on reference id
type: obtianing
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> +| authorized | abort | Payment was voided |
+| needs_init_data | abort | Payment aborted before initial data was verified |
+| none | abort | Payment aborted before initialization |
+| ready_for_settlement | abort | One party aborted the payment even though the other party already notified it is ready to settle the payment. For example, it may happen if the sender does not approve merchant data provided by the receiver
+
+### AbortCode Enum
+* `void`- This abort code should be used for voiding a payment that was previously authorized. For example, the merchant voided the payment because the purchased products are out of stock. It is expected that the sender VASP will respond with void code as a sign of agreement
+* `risk_checks_failed`- This abort code should be used when the risk checks performed based on the payer information failed
+* `rejected` - This abort code should be used for aborting a payment not covered by other values of the enum
+
+## New Command Types
+The following is a list of new values for the `command_type` field of the `CommandRequestObject`. Each command type denotes a step in the off-chain negotiations and specifies the data of the requests and the response
+* `InfoCommand` - Allows obtianing payment information based on reference id
+* `InitChargeCommand` - Initializes a payment process of type `charge`
+* `InitAuthorizeCommand` - Initializes a payment process of type `auth`
+* `ReadyNotification` - Notifies the payment is ready for settlement on-chain
I recommend we use the clearer but verbose version:
ReadyForSettlementNotification. Ready is too vague and requires cognitive
overhead to match w ready for settlement.
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> +
+### Abort Sequence - Risk Checks Failed
+| Step |Command Type| Triggered by | Description |
+|-|-|-|-|
+|1|InfoCommand|Sender|The wallet requests payment details using the reference id provided. The receiver will respond with the payment details and merchant data. The wallet will display the payment details so the customer can approve or reject|
+|2|InitChargeCommand / InitAuthorizeCommand|Sender|Following customer approval the wallet initializes the payment process and sends the payer data. Risk checks failed. Receiver will respond with abort status|
+
+### Abort Sequence - Merchant Data Checks (performed by the Sender) Failed
+| Step |Command Type| Triggered by | Description |
+|-|-|-|-|
+|1|InfoCommand|Sender|The wallet requests payment details using the reference id provided. The receiver will respond with the payment details and merchant data. The wallet will display the payment details so the customer can approve or reject|
+|2|InitChargeCommand / InitAuthorizeCommand|Sender|Following customer approval the wallet initializes the payment process and sends the payer data. The receiver will respond with appropriate success status|
+|3|AbortCommand|Sender|Sender decided to abort. Can happen if the sender does not approve merchant data provided by the receiver|
+
+---
+# Appendix A - Pre-requisite: Sharing Common Payment Identifier and Address
typo: Pre-requisite is not a hyphenated word. Prerequisite
<https://www.google.com/search?q=define+prerequisite&rlz=1C5GCEM_enUS929US929&oq=define+prerequi&aqs=chrome.0.0i324j69i57j0l5j0i22i30l3.2026j1j7&sourceid=chrome&ie=UTF-8>.
Same for other uses of pre-requisite in doc.
------------------------------
In dips/dip-8.md
<#166 (comment)>:
>
---
# Abstract / Motivation
---
-Version 0 of the Off-Chain Protocol is described in [DIP 1](https://dip.diem.com/dip-1/). Version 1 as described here is an extension of the Off-Chain Protocol and adds features to support more advanced functionality - particularly targeted to support merchant use-cases. This is inclusive of pull payments, recurring payments, and auth/capture flows.
+Versions 1/2 of the Off-Chain Protocol are described in [DIP 1](https://dip.diem.com/dip-1/).
+
+Version 3 as described here is an extension of the Off-Chain Protocol and adds features to support more advanced functionality - particularly targeted to support merchant use-cases.
+
+This DIP aimed to support a scenario of setting a Diem wallet as a long term payment method in an app or an eCommerce website.
nit: This DIP AIMS to support THE scenario
------------------------------
In dips/dip-8.md
<#166 (comment)>:
>
---
# Abstract / Motivation
---
-Version 0 of the Off-Chain Protocol is described in [DIP 1](https://dip.diem.com/dip-1/). Version 1 as described here is an extension of the Off-Chain Protocol and adds features to support more advanced functionality - particularly targeted to support merchant use-cases. This is inclusive of pull payments, recurring payments, and auth/capture flows.
+Versions 1/2 of the Off-Chain Protocol are described in [DIP 1](https://dip.diem.com/dip-1/).
+
+Version 3 as described here is an extension of the Off-Chain Protocol and adds features to support more advanced functionality - particularly targeted to support merchant use-cases.
+
+This DIP aimed to support a scenario of setting a Diem wallet as a long term payment method in an app or an eCommerce website.
+
+The high level flow is:
+1. The user asks to add their wallet to the app as a payment method
+2. The merchant VASP genereates a Funds Pull Pre Approval (FPPA) request
typo: genereates
------------------------------
In dips/dip-8.md
<#166 (comment)>:
>
---
# Abstract / Motivation
---
-Version 0 of the Off-Chain Protocol is described in [DIP 1](https://dip.diem.com/dip-1/). Version 1 as described here is an extension of the Off-Chain Protocol and adds features to support more advanced functionality - particularly targeted to support merchant use-cases. This is inclusive of pull payments, recurring payments, and auth/capture flows.
+Versions 1/2 of the Off-Chain Protocol are described in [DIP 1](https://dip.diem.com/dip-1/).
+
+Version 3 as described here is an extension of the Off-Chain Protocol and adds features to support more advanced functionality - particularly targeted to support merchant use-cases.
+
+This DIP aimed to support a scenario of setting a Diem wallet as a long term payment method in an app or an eCommerce website.
+
+The high level flow is:
+1. The user asks to add their wallet to the app as a payment method
+2. The merchant VASP genereates a Funds Pull Pre Approval (FPPA) request
+3. The user approves the FPA in their wallet (VASP)
Is it FPA or FPPA? If there's both can we explain both above.
------------------------------
In dips/dip-8.md
<#166 (comment)>:
> +# Disclaimer
+---
+
+This DIP does not contain the phase of exchanging identifiers between VASPs that is required to negotiate merchant scenarios.
+
+For the purpose of this document, we will assume that given a payment object with two VASP addresses and some underline indetifier, there is a protocol for exchaning these identities under VASPs (buyer and merchant) without revealing their identities to the public.
+
+The process described below starts at the phase that both sides have the relevant payment unique identifier (reference) and each VASP knows to corrlate it to its respectful entity under.
+
+---
+# Synonyms
+---
+
+For the sake of simplicity, we use the following terms:
+* "Buyer VASP" - The VASP who submits payment transactions to the blockchain in order to pay to the other VASP
+* "Merchant" - The VASP who recieves the funds (transaction)
Can we explicitly say Merchant VASP as we have other docs that have a lot
of communication between Merchant and Merchant VASP.
------------------------------
In dips/dip-8.md
<#166 (comment)>:
> +---
+# Disclaimer
+---
+
+This DIP does not contain the phase of exchanging identifiers between VASPs that is required to negotiate merchant scenarios.
+
+For the purpose of this document, we will assume that given a payment object with two VASP addresses and some underline indetifier, there is a protocol for exchaning these identities under VASPs (buyer and merchant) without revealing their identities to the public.
+
+The process described below starts at the phase that both sides have the relevant payment unique identifier (reference) and each VASP knows to corrlate it to its respectful entity under.
+
+---
+# Synonyms
+---
+
+For the sake of simplicity, we use the following terms:
+* "Buyer VASP" - The VASP who submits payment transactions to the blockchain in order to pay to the other VASP
We use Customer VASP in other DIPs, can we be consistent?
------------------------------
In dips/dip-8.md
<#166 (comment)>:
>
---
# Specification
---
-# Fund Pull Pre-Approval
-### *VERSION SUPPORT: Supported only in version 1 of off-chain APIs*
+### *VERSION SUPPORT: Supported only in version 3 of off-chain APIs*
+
+Establishes a relationship between a buyer VASP and a merchant where the merchant can then pull funds from the buyer VASP without the buyer user approving each transaction, like billing the user without an interaction for each payment. This relationship marked by a unique identifier, that is the `**funds_pull_pre_approval_id**`.
+
+## Funds pull pre approval request fields
+
+The following fields should be used to define a funds pull pre approval request. These fields should be encoded into a series of URL parameters appended to the query string. In case of QR code, the image should include the full link with all parameters.
+
+| Field | Type | Required? | Description |
+|------------------------|---------|------------|------------------------------------------------|
+| vasp_address | str | Y | Address of account from which billing will happen. The address is encoded using bech32 and should uniquly identify the merchant. For Diem addresses format, refer to the "account identifiers" section in [DIP-5](https://dip.diem.com/dip-5/#account-identifiers). |
typo: uniquly
------------------------------
In dips/dip-8.md
<#166 (comment)>:
>
---
# Specification
---
-# Fund Pull Pre-Approval
-### *VERSION SUPPORT: Supported only in version 1 of off-chain APIs*
+### *VERSION SUPPORT: Supported only in version 3 of off-chain APIs*
+
+Establishes a relationship between a buyer VASP and a merchant where the merchant can then pull funds from the buyer VASP without the buyer user approving each transaction, like billing the user without an interaction for each payment. This relationship marked by a unique identifier, that is the `**funds_pull_pre_approval_id**`.
+
+## Funds pull pre approval request fields
+
+The following fields should be used to define a funds pull pre approval request. These fields should be encoded into a series of URL parameters appended to the query string. In case of QR code, the image should include the full link with all parameters.
+
+| Field | Type | Required? | Description |
+|------------------------|---------|------------|------------------------------------------------|
+| vasp_address | str | Y | Address of account from which billing will happen. The address is encoded using bech32 and should uniquly identify the merchant. For Diem addresses format, refer to the "account identifiers" section in [DIP-5](https://dip.diem.com/dip-5/#account-identifiers). |
+| funds_pull_pre_approval_id | str | Y | A unique identifier of this pre-approval. Should be a UUID according to RFC4122 with "-"'s included. |
+| merchant_name | str | Y | The name of the biller |
I like the use of merchant here. Compared to DIP 158 however, our naming
seems inconsistent. In DIP 158 we're hesitant to be narrow and tight in our
definitions, and use "payment receiver" and the like. It would be great to
be consistent.
On that note, should this object be a PaymentReceiverObject? Seems like
no if entirely sent over URL.
------------------------------
In dips/dip-8.md
<#166 (comment)>:
> }
```
-### FundPullPreApprovalCommand object
-| Field | Type | Required? | Description |
-|------- |------ |----------- |------------- |
-| _ObjectType | str | Y | The fixed string `FundPullPreApprovalCommand` |
-| fund_pull_pre_approval| [`FundPullPreApprovalObject`](#fundpullpreapprovalobject) | Y | contains a `FundPullPreApprovalObject` that either creates a new pre-approval or updates an existing pre-approval. Note that strict validity checks apply when updating pre-approvals, that are listed in the section below describing these Objects. An invalid update or initial pre-approval object results in a Command error
-| _reads | JSON Object map | Y | Must be an Object containing mappings of `reference_id` to latest Version as represented by the `cid` of the latest Command which successfully mutated the Object referenced by the `reference_id`. The value in this field must match a `cid` previously specified by a Command by the `_writes` parameter on a prior Command for this payment Object. For a fund_pull_pre_approval Command, only zero or one `_reads` values should be specified since fund approvals are only dependent upon at most one prior Version of an Object. A list with any other number of items results in a Command error. If the list is empty this fund_pull_pre_approval Command defines a new fund_pull_pre_approval. If the list contains one item, then this Command updates the shared [`FundPullPreApprovalObject`](#fundpullpreapprovalobject). |
-| _writes | JSON object map | Y | For a fund_pull_pre_approval Command, the `_writes` field may only be a single key-value pair since a fund_pull_pre_approval Command only operates upon one Object. This field maps the `reference_id` of the Object being written to its new Version. |
+### FundsPullPreApprovalObject
+
+The structure in this object must be a full funds pull pre-approval and all fields beside the `status` are immutable after the creation. In order to change the status, one may send only the `funds_pull_pre_approval_id` and `status` fields. Updating immutable fields with different values results in a command error, but it is acceptable to re-send the same value.
+It should be noted that initial creation of the FundsPullPreApprovalObject can be done by the VASP on either side (buyer or merchant).
+
+
+#### ___The buyer creates the initial request___
+A merchant doesn't knows the buyer details upfront, so it use an out-of-band channel to request a consent (e.g. QR code). The buyer wallet (VASP) decode the request and initiate FundsPullPreApproval flow from its side
Just repeating the buyer/merchant link vs payment sender / payment
receiver used in DIP 158. Would love consistency.
------------------------------
In dips/dip-158.md
<#166 (comment)>:
> +| needs_init_data | ready_for_settlement | All required tasks were performed and the payment is ready for settlement |
+| needs_init_data | authorized | All required tasks were performed and the funds are ready to be locked |
+| authorized | ready_for_settlement | Funds captured |
+| authorized | abort | Payment was voided |
+| needs_init_data | abort | Payment aborted before initial data was verified |
+| none | abort | Payment aborted before initialization |
+| ready_for_settlement | abort | One party aborted the payment even though the other party already notified it is ready to settle the payment. For example, it may happen if the sender does not approve merchant data provided by the receiver
+
+### AbortCode Enum
+* `void`- This abort code should be used for voiding a payment that was previously authorized. For example, the merchant voided the payment because the purchased products are out of stock. It is expected that the sender VASP will respond with void code as a sign of agreement
+* `risk_checks_failed`- This abort code should be used when the risk checks performed based on the payer information failed
+* `rejected` - This abort code should be used for aborting a payment not covered by other values of the enum
+
+## New Command Types
+The following is a list of new values for the `command_type` field of the `CommandRequestObject`. Each command type denotes a step in the off-chain negotiations and specifies the data of the requests and the response
+* `InfoCommand` - Allows obtianing payment information based on reference id
Continuing on the trend of stronger and less vague names, I recommend
changing InfoCommand to PaymentInfoCommand
It's more consistent with the other names and narrows the scope of the
command. As is, Info is far too broad of a term that can be confused for
other flows and APIs. Making it more P2M specific will go a long way.
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#166 (review)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ASQRW5FWHBHGR2ZY3ZY2BEDTLGBCHANCNFSM43EEFMGA>
.
|
Main changes: * Removed DIP-8 fro the pull request * Change InfoCommand name * Added image_url to business_data * Spelling and grammar issues
|
@YinonFirstDAG After some more due diligence on traditional payment networks, the P2M data exchange is asymmetric: merchants share their name, address always, but customers often get away with just a name and zip code. Payer Data requires an address, but the fields in AddressObject are all optional. What would the flow be like when only needing zip from a customer? What would it be like it if we needed more? I think about https://github.com/firstdag/dip/blob/split-dip-8/dips/dip-158.md#payerdataobject |
|
Hi,
Thanks @dimitri Roche ***@***.***> for the comment above.
I assume that you mean that a zip code is provided together with the
country (and state if relevant). So basically, it's City, and Address
line(s) that will not be sent as part of the payer_data.
I see several options:
1. Define the address object in the DIP and make sure all the fields
mandatory (except address line 2)
2. The receiving VASP can state in the abort message what address fields
are missing. As discussed, there are no "step ups", this message will be
used for better error reporting, not to allow the sending VASP to send the
required information in a subsequent call
3. Add a structured object to indicate the missing address fields
(instead of putting them in the abort message)
Personally, I am leaning towards #1. It makes the flow clear and
unambiguous.
We can discuss this in tomorrow's meeting.
10x
Yinon Zohar
VP Product
+972-54-2428595
www.FirstDAG.com <http://www.firstdag.com/>
…On Tue, May 4, 2021 at 6:10 AM Dimitri Roche ***@***.***> wrote:
@YinonFirstDAG <https://github.com/YinonFirstDAG> After some more due
diligence on traditional payment networks, the P2M data exchange is
asymmetric: merchants share their name, address always, but customers often
get away with just a name and zip code. Payer Data requires an address, but
the fields in AddressObject are all optional. What would the flow be like
when only needing zip from a customer? What would it be like it if we
needed more? I think about needs_init_data and the return of specific
keys to indicate missing information.
https://github.com/firstdag/dip/blob/split-dip-8/dips/dip-158.md#payerdataobject
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#166 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ASQRW5FE2MDMGGTBLX4EJOLTL5QTVANCNFSM43EEFMGA>
.
|
|
Hi,
I went ahead and pushed a new version. It contains the 30 minutes
recommendation for the valid_until and specification of AddressObject with
the most fields as mandatory.
We can change this following our meeting tomorrow if we decide so.
I just want Daniel to be able to pull the latest version before adding the
dual attestation part.
Sorry about that.
10x
Yinon Zohar
VP Product
+972-54-2428595
www.FirstDAG.com <http://www.firstdag.com/>
…On Tue, May 4, 2021 at 11:12 AM Yinon Zohar ***@***.***> wrote:
Hi,
Thanks @dimitri Roche ***@***.***> for the comment above.
I assume that you mean that a zip code is provided together with the
country (and state if relevant). So basically, it's City, and Address
line(s) that will not be sent as part of the payer_data.
I see several options:
1. Define the address object in the DIP and make sure all the fields
mandatory (except address line 2)
2. The receiving VASP can state in the abort message what address
fields are missing. As discussed, there are no "step ups", this message
will be used for better error reporting, not to allow the sending VASP to
send the required information in a subsequent call
3. Add a structured object to indicate the missing address fields
(instead of putting them in the abort message)
Personally, I am leaning towards #1. It makes the flow clear and
unambiguous.
We can discuss this in tomorrow's meeting.
10x
Yinon Zohar
VP Product
+972-54-2428595
www.FirstDAG.com <http://www.firstdag.com/>
On Tue, May 4, 2021 at 6:10 AM Dimitri Roche ***@***.***>
wrote:
> @YinonFirstDAG <https://github.com/YinonFirstDAG> After some more due
> diligence on traditional payment networks, the P2M data exchange is
> asymmetric: merchants share their name, address always, but customers often
> get away with just a name and zip code. Payer Data requires an address, but
> the fields in AddressObject are all optional. What would the flow be like
> when only needing zip from a customer? What would it be like it if we
> needed more? I think about needs_init_data and the return of specific
> keys to indicate missing information.
>
>
> https://github.com/firstdag/dip/blob/split-dip-8/dips/dip-158.md#payerdataobject
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <#166 (comment)>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/ASQRW5FE2MDMGGTBLX4EJOLTL5QTVANCNFSM43EEFMGA>
> .
>
|
|
Another item I would like to add to tomorrow's agenda is ISO 8583, the standardized messaging framework between issuers and acquirers, the banks in a traditional payment network. |
davidiw
reviewed
May 4, 2021
davidiw
reviewed
May 4, 2021
* Removed usage of statuses
dimroc
reviewed
May 5, 2021
dimroc
reviewed
May 5, 2021
* Naming consistency * Optional redirect URL for QR flow (POS scenario)
Added diagram images
davidiw
approved these changes
May 6, 2021
tzakian
pushed a commit
to tzakian/lip
that referenced
this pull request
May 7, 2021
* Update dip-8.md * Update lip-8.md: Disclaimer regarding the discovery phase Extended scope for fund pull pre-approval Revoke an authorization in more details * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lip-8.md * Apply suggestions from code review Co-authored-by: kphfb <kph@fb.com> * PR fixes * split DIP-8 to funds pre approval and auth/capture * add dip 158 for p2m charge + auth/capture * Created DIP-158 (AKA P2M DIP). * Incorporated additional comments * Update dip-8.md * Update lip-8.md: Disclaimer regarding the discovery phase Extended scope for fund pull pre-approval Revoke an authorization in more details * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lip-8.md * Apply suggestions from code review Co-authored-by: kphfb <kph@fb.com> * PR fixes * split DIP-8 to funds pre approval and auth/capture * add dip 158 for p2m charge + auth/capture * Created DIP-158 (AKA P2M DIP). * Incorporated additional comments * Revert DIP-8 initial changes draft * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Updated based on latest comments from Dahlia * Added glossary item for Reference ID based on Dahlia's comments. * Update dips/dip-158.md Co-authored-by: David Wolinsky <isaac.wolinsky@gmail.com> * Update dips/dip-158.md Co-authored-by: David Wolinsky <isaac.wolinsky@gmail.com> * Updated based on David W. comments * Additional comments following meeting with the team. Notes: Agreed that we will create new structures for P2M purposes rather than impose changes on existing structures from 0 < DIP < 2 (did not want to use the actual DIP name :)). For example, we will NOT extend or change the PaymentActorObject. Instead, we will create a new object suitable for P2M needs (e.g. BusinessActorObject). Agreed that business_data (i.e. merchant basic details) should be part of the InfoCommand response Agreed that payer_data (i.e. payer information) should be part of the InitCommand(s) request Agreed that, for the time being, there is no support for an additional step to ask for more data. The receiving VASP can either accept or reject the payment based on the information provided. We mentioned that the receiving VASP should be able to state "extra" information that is required on top of the payer_data (e.g. DOB might be required for buying alcohol) as part of the InfoCommand response. This will be achieved by an additional optional element (type will be JSON) A similar optional element will be added to the InitCommand(s) request. This element is to be used by the sending VASP to send the additional information requested (e.g. DOB) Agreed (with a heavy heart...) to stop using the functionality names and stick with the command types Agreed to use two different init command types (for each payment type) to replace the single InitCommand We will change the name of the ReadyCommand to be ReadyNotification Add dual attestation specification for transactions over the limit * Revert DIP-8 to master version to remove from pull request * Another cycle of comments incorporated. Main changes: * Removed DIP-8 fro the pull request * Change InfoCommand name * Added image_url to business_data * Spelling and grammar issues * Changed the order of sections and added internal links * Internal links fix * Appendix A link * Added AddressObject and NationalIdObject * * Introduced PaymentCommandErrorObject * Removed usage of statuses * add dual attestation info to charge command response and capture command request * * Grammar issue * Naming consistency * Optional redirect URL for QR flow (POS scenario) * Added sequence diagrams and partial capture support * Update dip-158.md Added diagram images Co-authored-by: kphfb <kph@fb.com> Co-authored-by: Karpick-E <59393941+Karpick-E@users.noreply.github.com> Co-authored-by: Daniel Prinz <daniel@firstdag.com> Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> Co-authored-by: David Wolinsky <isaac.wolinsky@gmail.com>
tzakian
pushed a commit
to tzakian/lip
that referenced
this pull request
May 7, 2021
* Update dip-8.md * Update lip-8.md: Disclaimer regarding the discovery phase Extended scope for fund pull pre-approval Revoke an authorization in more details * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lip-8.md * Apply suggestions from code review Co-authored-by: kphfb <kph@fb.com> * PR fixes * split DIP-8 to funds pre approval and auth/capture * add dip 158 for p2m charge + auth/capture * Created DIP-158 (AKA P2M DIP). * Incorporated additional comments * Update dip-8.md * Update lip-8.md: Disclaimer regarding the discovery phase Extended scope for fund pull pre-approval Revoke an authorization in more details * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lips/lip-8.md Co-authored-by: kphfb <kph@fb.com> * Update lip-8.md * Apply suggestions from code review Co-authored-by: kphfb <kph@fb.com> * PR fixes * split DIP-8 to funds pre approval and auth/capture * add dip 158 for p2m charge + auth/capture * Created DIP-158 (AKA P2M DIP). * Incorporated additional comments * Revert DIP-8 initial changes draft * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Update dips/dip-158.md Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> * Updated based on latest comments from Dahlia * Added glossary item for Reference ID based on Dahlia's comments. * Update dips/dip-158.md Co-authored-by: David Wolinsky <isaac.wolinsky@gmail.com> * Update dips/dip-158.md Co-authored-by: David Wolinsky <isaac.wolinsky@gmail.com> * Updated based on David W. comments * Additional comments following meeting with the team. Notes: Agreed that we will create new structures for P2M purposes rather than impose changes on existing structures from 0 < DIP < 2 (did not want to use the actual DIP name :)). For example, we will NOT extend or change the PaymentActorObject. Instead, we will create a new object suitable for P2M needs (e.g. BusinessActorObject). Agreed that business_data (i.e. merchant basic details) should be part of the InfoCommand response Agreed that payer_data (i.e. payer information) should be part of the InitCommand(s) request Agreed that, for the time being, there is no support for an additional step to ask for more data. The receiving VASP can either accept or reject the payment based on the information provided. We mentioned that the receiving VASP should be able to state "extra" information that is required on top of the payer_data (e.g. DOB might be required for buying alcohol) as part of the InfoCommand response. This will be achieved by an additional optional element (type will be JSON) A similar optional element will be added to the InitCommand(s) request. This element is to be used by the sending VASP to send the additional information requested (e.g. DOB) Agreed (with a heavy heart...) to stop using the functionality names and stick with the command types Agreed to use two different init command types (for each payment type) to replace the single InitCommand We will change the name of the ReadyCommand to be ReadyNotification Add dual attestation specification for transactions over the limit * Revert DIP-8 to master version to remove from pull request * Another cycle of comments incorporated. Main changes: * Removed DIP-8 fro the pull request * Change InfoCommand name * Added image_url to business_data * Spelling and grammar issues * Changed the order of sections and added internal links * Internal links fix * Appendix A link * Added AddressObject and NationalIdObject * * Introduced PaymentCommandErrorObject * Removed usage of statuses * add dual attestation info to charge command response and capture command request * * Grammar issue * Naming consistency * Optional redirect URL for QR flow (POS scenario) * Added sequence diagrams and partial capture support * Update dip-158.md Added diagram images Co-authored-by: kphfb <kph@fb.com> Co-authored-by: Karpick-E <59393941+Karpick-E@users.noreply.github.com> Co-authored-by: Daniel Prinz <daniel@firstdag.com> Co-authored-by: dahliamalkhi <dahliamalkhi@outlook.com> Co-authored-by: David Wolinsky <isaac.wolinsky@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Created DIP-158 containing eCommerce P2M Payments flows.
Resolves #158