Payments and Transactions
Payments are always created first
Payments
Payments are central to the Modulr platform, serving as the primary repository for payment data. For instance, when an outbound payment is requested through our Create Payment API, it undergoes initial validation and processing, passing through some “transient” statuses. You should only rely on the Final Status for reconciliation purposes, please see all payment statuses.
A final successful payment request will be “Processed,” and because the payment request is successful we also create a transaction, which represents the debit on the relevant account and is linked to its "source" payment. The sourceID of a transaction corresponds to its paymentID (PBid). While both stages have their own Modulr references, a payment is always created first. Payments and Transactions also exist for other payment types, e.g. via card activity or direct debits.
Inbound payments credited to an account will be both a payment and a transaction on our platform.
Outbound requests may consist solely of a payment if they are not processed successfully but will include both a payment and a transaction when successful.
Payment / Transaction Types
The type will indicate the scheme used and direction, so a PI_FAST is an “Payment Inbound via Faster Payments” and will be a credit to an account.
The list of all Payment Types.
API Calls to Aid with Statements and Reconciliation
Retrieve Payments is a GET API call and provides information from Modulr on a payment, especially for returns, status and for calls using a range of different payment parameters. This call is also referred to as GetPayments.
Get Transactions by Account is also a GET API call provides data on only processed payments for a specified account (all credits/debits). It is a smaller dataset (compared to GetPayments), to provide consistency across different payment and card schemes. This call is also referred to as GetTransactions.
External References
These are optional parameters in the API calls, but we strongly recommend you provide your own reference data. Each is a 50 character string using alphanumeric characters, underscore, hyphen and space. They appear as part of each Customer, Account, Payment and Card record and are also editable against both the Customer and Account.
- Customer: Ideally your system/CRM identifier for the Customer
- Account: This is often an alias name possibly with the purpose of the account you also have available the Modulr ABid, Sort Code/Account Number or IBAN
- Payment: Your code to directly connect an outbound payment request to your system (this is NOT the payment scheme reference sent with the payment)
- Card: This is often an alias name, possibly with the purpose of the card or category of spend used
The externalReference appears in all relevant webhooks and the Get Payments endpoint (but not on Get Transactions). An inbound payment sent from an external source cannot contain such a reference, but it can on be used on payments sent between Modulr accounts (internal transfers).
Payment Scheme ID
The data from all payments via the payment schemes is also made available with their own scheme references. The scheme ID of an outbound payment request is not created until Modulr sends the payment to the underlying scheme.
The PAYOUT webhook will contain the scheme Id, it also becomes available via GetPayments after we've performed the debit for that payment from the account. Combining Pbids, your external references, and payment references along with payment scheme IDs will provide a comprehensive data set to perform your own reconciliation.
Updated 5 days ago