Payments agent
The Payments Agent CorDapp is hosted by a trusted member of a network, such as the Business Network Operator (BNO). In this technical preview, you can assign the role of Payments Agent to a node on your local network by adding the CorDapp to that node.
Payments Agent and the PSP
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
In the role of Payments Agent on a network, you are responsible for the connection between your node and the Payment Service Provider (PSP) you are using—in the technical preview, this is Modulr. You must have an account with Modulr in order to act as the Payments Agent, and to make use of this technical preview.
Customers of the Payments Agent
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
As the Payments Agent, you can consider members of your network who wish to make payments as your customers. In this documentation, any reference to a customer or customer ID refers to members of a network who wish to make payments using Corda Payments with you as their Payments Agent.
Before you can create accounts for a party on your network, you must add them as a customer.
Using the Payments Agent CorDapp, you can manage your customers’ payment accounts and payment requests. You can use the Payments Agent CorDapp endpoints to connect to a UI to perform tasks as required.
Payments Agent flows
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
The Payments Agent CorDapp provides flows that correspond to API endpoints. You can use these flows to:
- Close an account. CloseAccountDetails.
- Close down the customer details on the vault. CloseCustomerDetails.
- Create a customer account state object in the vault. CreateAccountDetails.
- Create a customer details state in the vault. CreateCustomerDetails.
- Get the balance of an account. GetAccountBalance.
- Get a list of available PSPs. GetAvailablePSPs.
- Get a list of available currencies available to the Payments Agent. GetCurrenciesOnAgent.
- Get a list of customer accounts. GetCustomerAccounts.
- Get a payment account. GetPaymentAccount.
- Get a list of customers that you manage on the PSP. GetPSPAccounts.
- Return a page of customers managed by the agent on the PSP. GetPSPCustomers.
- Return the specification of the PSP. GetPSPSpecification.
- Return a list of transactions based on specified criteria. GetTransactions.
- Update details of a customer by updating the details state object in the vault. UpdateCustomerDetails.
CloseAccountDetails
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Close an account state on the vault.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
accountId
. The account ID in the vault.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@StartableByService
@Suppress("unused")
class CloseAccountDetails(
private val accountId: PaymentAccountId
) : CloseAccountDetailsInitiator()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<Unit>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(
::CloseAccountDetails,
accountId
)
CloseCustomerDetails
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Close a customer details state on the vault.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
customerId: PaymentCustomerId
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@StartableByService
@Suppress("unused")
class CloseCustomerDetails(
private val customerId: PaymentCustomerId
) : CloseCustomerDetailsInitiator()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<CustomerDetailsState>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::CloseCustomerDetails, customerId)
CreateAccountDetails
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Create a customer account state object in the vault.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
accountName
. Account name.currency
. Account currency.customerId
. Existing customer who will own the account.pspAccountId
. Optional. Existing Modulr account to link to.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@Suppress("unused")
class CreateAccountDetails(
private val accountName: String,
private val currency: String,
private val customerId: String,
private val pspAccountId: String?
) : CreateAccountDetailsInitiator()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<PaymentAccountDetailsState>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(
::CreateAccountDetails,
accountName,
currency,
customerId,
pspAccountId
)
CreateCustomerDetails
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Create a payment customer details state object in the vault. If the customer already exists then a flow exception is thrown.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
paymentCustomer
. Customer name.details
. Customer details.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@Suppress("unused")
class CreateCustomerDetails(
private val paymentCustomer: PaymentCustomer,
private val details: Map<String, Any>
) : CreateCustomerDetailsInitiator()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<CustomerDetailsState>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::CreateCustomerDetails, customer, details)
GetAccountBalance
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return the AccountBalance
for a given accountId
. Internal flow logic for use by responder and direct for agent UI interactions.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
accountId
. The ID associated with the account.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
class GetAccountBalance(
private val accountId: PaymentAccountId
) : FlowLogic<AccountBalance>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<AccountBalance>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(
::GetAccountBalance,
accountId
)
GetAvailablePSPs
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Returns a list of the PSPs that are configured on the Payments application.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
None.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetAvailablePSPs : FlowLogic<List<String>>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<List<String>>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetAvailablePSPs)
GetCurrenciesOnAgent
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return all currencies provided by the Payments Agent’s PSPs integrations.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
None.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
class GetCurrenciesOnAgent() : FlowLogic<Set<FiatCurrency>>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<Set<FiatCurrency>>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetCurrenciesOnAgent)
GetCustomerAccounts
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return a list of accounts associated with a customer.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
private val customerId: String
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetCustomerAccounts(private val customerId: String) : FlowLogic<List<PaymentAccount>>() {
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<List<PaymentAccount>>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetCustomerAccounts, customerId)
GetPaymentAccount
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return the PaymentAccount
for a given PaymentAccountId
. Internal flow logic for use by responder and direct for agent UI interactions.
Will return from local cache map if available; else fetches from vault query, adds to cache, then returns.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
paymentAccountId: PaymentAccountId
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
class GetPaymentAccount(private val paymentAccountId: PaymentAccountId) : FlowLogic<PaymentAccount>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<PaymentAccount>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetPaymentAccount, paymentAccountId)
GetPSPAccounts
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return a page of customers managed by the agent on the PSP.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Search criteria.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
class GetPSPAccounts(
private val criteria: AccountDetailsCriteria
) : FlowLogic<PagedResponse<AccountDetails>>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<PagedResponse<AccountDetails>>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetPSPAccounts, criteria)
GetPSPCustomers
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return a page of customers managed by the agent on the PSP.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Search criteria.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
class GetPSPCustomers(
private val criteria: CustomerDetailsCriteria
) : FlowLogic<PagedResponse<CustomerDetails>>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<PagedResponse<CustomerDetails>>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetPSPCustomers, criteria)
GetPSPSpecification
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Returns a PSP specification.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
private val psp: String
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetPSPSpecification(private val psp: String) : FlowLogic<PSPSpecification>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<PSPSpecification>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetPSPSpecification, psp.toUpperCase())
GetTransactions
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Return the transaction history of an account.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
accountId:
String. The account ID.criteria: PaymentTransactionCriteria
.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetTransactions(
private val accountId: String,
private val criteria: PaymentTransactionCriteria
) : FlowLogic<PagedResponse<PaymentTransaction>>()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<PagedResponse<PaymentTransaction>>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(::GetTransactions, accountId, criteria)
UpdateCustomerDetails
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Update a payment customer details state object in the vault.
Parameters
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
customerId
. Customer Id.
details
. Customer details.
deleted
. Customer details to be deleted.
Flow signature
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
@StartableByRPC
@Suppress("unused")
class UpdateCustomerDetails(
private val customerId: PaymentCustomerId,
private val details: Map<String, Any>,
private val deleted: List<String> = emptyList()
) : UpdateCustomerDetailsInitiator()
Return type
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
FlowLogic<CustomerDetailsState>
Example
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
startFlow(
::UpdateCustomerDetails,
customerId,
details,
deleted
)
Was this page helpful?
Thanks for your feedback!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.
We're sorry this page wasn't helpful. Let us know how we can make it better!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Create an issue
Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.