developers.diem.com/docs/wallets-and-merchant-stores/integrate-wallet-merchant-dpn.md
If you are a qualified Regulated VASP, use this guide to integrate your wallet or merchant store with the Diem Payment Network (DPN).
To become a qualified Regulated VASP, Diem Networks needs to authorize you to be a participant on the DPN.
To integrate your wallet or merchant store with the DPN, you need to:
Regulated VASP accounts are reserved for a Regulated VASP that operates on the DPN usually on behalf of end users. There are two types of Regulated VASP accounts, ParentVASP accounts and ChildVASP accounts.
ParentVASP accounts: The ParentVASP account is your unique root account. You can have only one parent account per Regulated VASP. Diem Networks will create a ParentVASP account on your behalf with your authentication key. This parent account contains three key pieces of data:
human_name: Your unique account name.base_url: The URL containing an endpoint to hit that off-chain APIs use to exchange information to comply with the Travel Rule. This will contain a dummy value when the ParentVASP account is created.compliance_public_key: An ed5519 public key for authenticating signatures on Travel Rule payloads. This will contain a dummy value when the account is created.ChildVASP accounts: The ChildVASP account is the child of your ParentVASP account. A ChildVASP account stores the address of its ParentVASP. You can have any number of ChildVASP accounts. They can help in maintaining a structured on-chain presence (e.g., separate cold/warm/hot accounts). You do not need to have ChildVASP accounts.
Read the accounts page to learn more.
To create your VASP accounts: <small className="figure">Figure 1.0 Creating your VASP account</small>
XUS or ALL, and a human-readable VASP name to use on-chain. Diem Networks will need to check if the human name is a unique value.When you are creating your ParentVASP account, you will need to choose at least one Diem Coin currency. The Diem Coin currency that is currently available on the DPN is XUS(a USD stablecoin).
When there is more than one Diem Coin currency available, you can share with the DPN which one you would like to associate with your account. You can also request the DPN to choose all the Diem Coin currencies available.
You can add new Diem Coin currencies to an existing account via the add_currency_to_account transaction script. You can add all currencies offered on the DPN to your ChildVASP accounts by using the add_all_currencies flag in the account creation scripts.
When available, at the Move level, each Diem Coin currency will be a different generic instantiation of the same Diem type (i.e. Diem<XUS>).
When you submit a transaction to the DPN, you are cryptographically signing a transaction script and then waiting (by listening to the event stream) for consensus from validators. Learn more about the lifecycle of a transaction.
Once you have your ParentVASP account, you can start interacting with the DPN. Before you submit your first transaction, you will need to:
The first step to submitting transactions to the DPN is determining how to connect and interact with it. The guidance for this differs slightly based on if you are a validator node operator or not.
If you are not a validator node operator, you can do one of the following:
Your wallet integration with the DPN may be faster when done using the JSON-RPC service.
Off-chain protocols are APIs and payload specifications that support compliance and scalability on the DPN. It is executed between pairs of Regulated VASPs, such as wallets, exchanges, or designated dealers, and allows Regulated VASPs to privately exchange payment information before, while, or after settling it on the Diem Blockchain.
These off-chain APIs also provide a means to to comply with the Travel Rule and negotiate one-time identifiers for on-chain transactions, reducing transaction linkability. To establish a connection, VASPs will look up their counterparty’s on-chain account containing a base URL for their off-chain service. Note that each entity using an Off-Chain API must make its own determination as to whether it satisfies Travel Rule compliance.
To use off-chain APIs, you will need to set values for the base_url and compliance_public_key associated with your on-chain ParentVASP account.
You can read more about off-chain protocols here.
When an account submits a transaction for execution, gas is used to:
Learn more about using gas to specify a transaction fee here
To compute a transaction fee, you can choose the following gas values:
| Definition | Set value |
|---|---|
max_gas_units | The maximum amount of gas units that can be used to execute a transaction. This bounds the computational resources that can be consumed by a transaction. To help you choose a value for max_gas_amount, we will be publishing a list of suggested max_gas_amount for each transaction before launch. We will be keeping the current lockdown restrictions the world-over in consideration for this list. |
On testnet: 600 < max_gas_amount ≤ 2,000,000 |
| gas_price | The number of gas units used in the specified gas currency. Gas price is a way to move from gas units, the abstract units of resource consumption the virtual machine (VM) uses, into a transaction fee in the specified gas currency. For launch, you can set the gas_price to be zero or almost zero, allowing you to submit transactions without high charges. This is because the network shouldn’t have high contention.
On testnet: 0 ≤ gas_price ≤ 10,000 |
| gas_currency_code | This is the currency of the transaction fee charged to the client. The gas_currency must be a registered currency on-chain ("XUS" on testnet), and must be one of the held currencies of the sending account. E.g. setting the gas_currency to "Coin3" would cause the transaction to be rejected since Coin3 is not a registered currency on-chain, and the sending account does not hold that currency. |
If you're a Regulated VASP who wants to build and integrate your own merchant store, you will need to set up direct payments to receive payments and handle refunds.
When the DPN launches, we expect that wallets will support a basic set of payment flows that resemble peer-to-peer transactions. Accordingly, the initial range of merchant checkout options will be limited to direct payments, which are single point-in-time transactions with a known amount and currency type.
To provide an interoperable checkout experience, you will need to share payment information or context with the end user. This can happen through a generated QR code, a URI that you can copy and paste, or a mobile deep link.
This information includes:
Once the end user's wallet service provider (Regulated VASP) receives this payment context, it can now construct a pre-populated payment for the user to authorize.
When the end user authorizes their wallet to pay the merchant per the shared payment context, their wallet will go through a similar sender flow to a peer-to-peer payment. A transaction is committed directly on-chain as long as the amount doesn't exceed the Travel Rule threshold. If the Travel Rule goes into effect, the payment will first be preflighted through the off-chain protocol, before being committed on-chain.
More information about payment request URI serialization can be found here.
Once the end user's wallet sends you, a merchant service provider, the payment, you can check the transaction to connect it to a checkout session, confirm the payment, and signal the confirmation to the end user.
You can do this by interfacing with a FullNode to track emitted events for your on-chain accounts. If you see that you have received a payment, you can examine the accompanying subaddress to route the payment internally. Since the subaddress will be unique for each transaction, you can determine who the buyer (end user who sent you the payment) was. In other words, you can connect the payment received to a checkout session and signal that the payment is confirmed to the end user.
You may want to issue a refund to a customer in some cases such as when you receive duplicate payments, a payment to an invalid address, when a customer returns a purchase, or because of some customer support inquiry.
Refunds on the DPN resemble any other peer-to-peer transaction. A merchant service provider would need to construct a transaction script on behalf of the merchant, and submit it to the original customer. These transactions are subject to the Travel Rule controls and will require off-chain preflighting if the amount exceeds the Travel Rule threshold.
Unlike other transactions, refunds will contain a pointer to the original transaction that they correspond to. If the transaction exceeds the Travel Rule threshold, the original event reference id is included in the off-chain payload. Otherwise (ie. in the non-Travel Rule case), the original event sequence number is sent in the on-chain body of the refund transaction. Wallets that receive these refunds can use the reference to the original transaction to provide additional context to the inbound funds.
More information about refunds can be found here. Additional information about transaction serialization can be found here.
You can send payments using this transaction script.
This script requires the following:
CoinType. The zero balance is added when the CoinType currency is authorized for an account. This means if the sending or receiving account doesn’t have a balance (or a zero balance) in the currency specified by CoinType, the transaction will abort.CoinType specifying the currency to be transferred.Each transaction is designed to emit any number of events as a list. An aborting transaction never emits events, so you can use events to confirm if a transaction has been successfully executed.
For example, a peer-to-peer payment transaction emits a SentPayment event for the sender’s account and a ReceivedPayment event for the recipient account. The SentPayment event allows the sender to confirm that the payment was sent from their account, while a ReceivedPayment event allows the recipient to confirm that a payment was received in their account. Events are persisted on the Diem Blockchain and you (as a Regulated VASP) can use these events to answer your queries.
More information on event structures, and how they can be queried and the surrounding data in the JSON responses can be found here.
To check for new transactions posted to your account, you need to query the blockchain using the JSON-RPC endpoints.