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.

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.

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.

The Payments Agent CorDapp provides flows that correspond to API endpoints. You can use these flows to:

Close an account state on the vault.

accountId. The account ID in the vault.

@StartableByRPC
@StartableByService
@Suppress("unused")
class CloseAccountDetails(
    private val accountId: PaymentAccountId
) : CloseAccountDetailsInitiator()
FlowLogic<Unit>
startFlow(
    ::CloseAccountDetails,
    accountId
)

Close a customer details state on the vault.

customerId: PaymentCustomerId

@StartableByRPC
@StartableByService
@Suppress("unused")
class CloseCustomerDetails(
    private val customerId: PaymentCustomerId
) : CloseCustomerDetailsInitiator()
FlowLogic<CustomerDetailsState>
startFlow(::CloseCustomerDetails, customerId)

Create a customer account state object in the vault.

  • accountName. Account name.
  • currency. Account currency.
  • customerId. Existing customer who will own the account.
  • pspAccountId. Optional. Existing Modulr account to link to.
@StartableByRPC
@Suppress("unused")
class CreateAccountDetails(
    private val accountName: String,
    private val currency: String,
    private val customerId: String,
    private val pspAccountId: String?
) : CreateAccountDetailsInitiator()

FlowLogic<PaymentAccountDetailsState>

startFlow(
    ::CreateAccountDetails,
    accountName,
    currency,
    customerId,
    pspAccountId
)

Create a payment customer details state object in the vault. If the customer already exists then a flow exception is thrown.

  • paymentCustomer. Customer name.
  • details. Customer details.
@StartableByRPC
@Suppress("unused")
class CreateCustomerDetails(
    private val paymentCustomer: PaymentCustomer,
    private val details: Map<String, Any>
) : CreateCustomerDetailsInitiator()
FlowLogic<CustomerDetailsState>
startFlow(::CreateCustomerDetails, customer, details)

Return the AccountBalance for a given accountId. Internal flow logic for use by responder and direct for agent UI interactions.

  • accountId. The ID associated with the account.
@StartableByRPC
class GetAccountBalance(
    private val accountId: PaymentAccountId
) : FlowLogic<AccountBalance>()
FlowLogic<AccountBalance>
startFlow(
    ::GetAccountBalance,
    accountId
)

Returns a list of the PSPs that are configured on the Payments application.

None.

@StartableByRPC
@StartableByService
@Suppress("unused")
class GetAvailablePSPs : FlowLogic<List<String>>()
FlowLogic<List<String>>
startFlow(::GetAvailablePSPs)

Return all currencies provided by the Payments Agent’s PSPs integrations.

None.

@StartableByRPC
class GetCurrenciesOnAgent() : FlowLogic<Set<FiatCurrency>>()
FlowLogic<Set<FiatCurrency>>
startFlow(::GetCurrenciesOnAgent)

Return a list of accounts associated with a customer.

private val customerId: String
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetCustomerAccounts(private val customerId: String) : FlowLogic<List<PaymentAccount>>() {
FlowLogic<List<PaymentAccount>>
startFlow(::GetCustomerAccounts, customerId)

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.

paymentAccountId: PaymentAccountId

@StartableByRPC
class GetPaymentAccount(private val paymentAccountId: PaymentAccountId) : FlowLogic<PaymentAccount>()
FlowLogic<PaymentAccount>
startFlow(::GetPaymentAccount, paymentAccountId)

Return a page of customers managed by the agent on the PSP.

Search criteria.

@StartableByRPC
class GetPSPAccounts(
    private val criteria: AccountDetailsCriteria
) : FlowLogic<PagedResponse<AccountDetails>>()
FlowLogic<PagedResponse<AccountDetails>>
startFlow(::GetPSPAccounts, criteria)

Return a page of customers managed by the agent on the PSP.

Search criteria.

@StartableByRPC
class GetPSPCustomers(
    private val criteria: CustomerDetailsCriteria
) : FlowLogic<PagedResponse<CustomerDetails>>()
FlowLogic<PagedResponse<CustomerDetails>>
startFlow(::GetPSPCustomers, criteria)

Returns a PSP specification.

private val psp: String
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetPSPSpecification(private val psp: String) : FlowLogic<PSPSpecification>()
FlowLogic<PSPSpecification>
startFlow(::GetPSPSpecification, psp.toUpperCase())

Return the transaction history of an account.

  • accountId: String. The account ID.
  • criteria: PaymentTransactionCriteria.
@StartableByRPC
@StartableByService
@Suppress("unused")
class GetTransactions(
    private val accountId: String,
    private val criteria: PaymentTransactionCriteria
) : FlowLogic<PagedResponse<PaymentTransaction>>()
FlowLogic<PagedResponse<PaymentTransaction>>
startFlow(::GetTransactions, accountId, criteria)

Update a payment customer details state object in the vault.

customerId. Customer Id. details. Customer details. deleted. Customer details to be deleted.

@StartableByRPC
@Suppress("unused")
class UpdateCustomerDetails(
    private val customerId: PaymentCustomerId,
    private val details: Map<String, Any>,
    private val deleted: List<String> = emptyList()
) : UpdateCustomerDetailsInitiator()
FlowLogic<CustomerDetailsState>
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.