Payment lifecycle
The payment lifecycle encompasses the entire journey of a payment through our system - from initiation to final settlement. This section provides comprehensive documentation on how payments are processed, tracked, and managed.
In this page and sub-pages, you'll find detailed information about:
- Different payment initiation options and configurations
- Processing of both incoming and outgoing payments
- Payment routing logic and settlement networks
- Payment status tracking and notifications
- Handling recalls and payment traces
- Third-party initiated payments (Direct Debits)
Payment Endpoints Overview
Our API provides comprehensive endpoints for managing different types of payments throughout their lifecycle. Here's an overview of the available endpoints by category:
Single Payments
Single payment endpoints allow you to process and manage individual payment transactions. Use these endpoints when you need to initiate and track individual payments.
| Endpoint Description | API Reference | Notes |
|---|---|---|
| Initiate a single payment | POST api/v1/payments/singles | Creates a new payment. Supports various payment schemes, currencies and options. Returns a payment ID for tracking. |
| Get list of payments | GET api/v1/payments/singles | Returns paginated list of payments. Supports filtering by status, date range, and other criteria. |
| Get payment status | GET api/v1/payments/singles/{payment-id}/status | Quick status check without full payment details. Use for efficient polling. See Outgoing payments to understand how statuses work. |
| Get payment details | GET api/v1/payments/singles/{payment-id} | Returns complete payment information including processing history and current status. |
| Cancel payment | PUT api/v1/payments/singles/{payment-id}/cancel | Only available for payments not yet processed. Returns error if payment is already processed. See Outgoing payments to understand when you can cancel a payment. |
| Reject outgoing direct debit | PUT api/v1/payments/singles/{payment-id}/reject | For rejecting or incoming direct debits. See Direct Debit payments (3rd party-initiated payments). |
| Get MT103 confirmation | GET api/v1/payments/singles/{payment-id}/mt103 | Returns a payment confirmation in MT103 message format for a single payment. |
| Get payment by transaction reference | GET api/v1/payments/singles/transactionreference/{transactionreference} | Alternative lookup method using the transaction reference instead of payment ID. |
Bulk Payments
Bulk payment endpoints enable efficient processing of multiple payments in a single request. Ideal for batch processing scenarios. For more information about bulk files, see Bulk Payments.
| Endpoint Description | API Reference | Notes |
|---|---|---|
| Initiate bulk payments | POST api/v1/payments/bulks | Submit a CSV file containing multiple payment instructions. |
| Get list of bulk files | GET api/v1/payments/bulks | Retrieve a paginated list of all bulk payments, with an detailed statistics for each bulk including: overall bulk status, payment statistics with counts for each status, total number of payments, and aggregated amount. |
| Get bulk file details | GET api/v1/payments/bulks/{payment-bulk-id} | Retrieve detailed statistics for a bulk payment, including: overall bulk status, payment statistics with counts for each status, total number of payments, and aggregated amount. |
| Get bulk payment status | GET api/v1/payments/bulks/{payment-bulk-id}/status | Returns the aggregated status of a single bulk. |
| Cancel bulk payments | PUT api/v1/payments/bulks/{payment-bulk-id}/cancel | Cancel all cancellable payments within a bulk submission. The system will attempt to cancel each individual payment, apply the same cancellation rules as single payments, allow partial cancellation if some payments are already processed, and return a summary of which payments were successfully cancelled. |
| Retrieve list of payments within a bulk file | GET /api/v1/payments/singles?paymentBulkId={payment-bulk-id} | Retrieve all individual payments within a specific bulk submission for detailed tracking. |
Agency and Correspondent Banking
Specialized endpoints for agency and correspondent banking operations.
| Endpoint Description | API Reference | Notes |
|---|---|---|
| Initiate agency/correspondent payment | POST /api/v1/payments/fi-to-fi-customer-credit-transfer-initiation | For financial institutions only. Requires special permissions and additional header authentication. |
ISO20022 Payments
We offer support for standardized ISO20022 payment formats, enabling you to submit payments using industry-standard message formats. See ISO20022 message formats for detailed implementation guidelines.
| Endpoint Description | API Reference | Notes |
|---|---|---|
| Payment initiation (pain.001) | POST /api/v1/payments/iso20022/customer-credit-transfer-initiation | Customer credit transfer initiation. Supports both single and batch payments. |
| Payment instruction (pacs.008) | POST /api/v1/payments/iso20022/fi-to-fi-customer-credit-transfer | FI-to-FI credit transfer. Only available for financial institutions. |
Payment Investigation
When you need to track down payment issues or request information about processed payments, we offer investigation tools. See payment recalls and traces for detailed information about payment investigation options and best practices.
Updated 7 days ago