PayTo API

What is an MPIR?

A Mandate Payment Initiation Request (MPIR) is a request submitted by a business to initiate payments based on an underlying mandate agreement. The mandate outlines the agreement between the payer and the payee, authorizing the payer’s bank to process payments on the payer’s behalf.

In the PayTo payment ecosystem, MPIRs play a crucial role in automating payment processes. When an MPIR is submitted, it initiates the payment flow as specified by the mandate. MPIRs can be processed as single transactions via API or as bulk transactions when multiple payments need to be handled together in a file format.

Key elements of an MPIR include:

• Mandate Identification: The unique ID representing the agreement authorizing the payment.
• Payment Details: Information such as the amount to be paid, the beneficiary’s details, and the payment schedule.
• Transaction Status Tracking: The ability to track the status of each payment, ensuring visibility and control over the payment lifecycle.

For bulk payments, MPIRs are submitted in a file that contains multiple payment instructions, each uniquely identified for processing. This enables businesses to efficiently handle high volumes of payments through a single submission.

Where Payment initiation fits in the PayTo process flow:

The diagram below illustrates the steps involved in the PayTo process and highlights where Mandate Payment Initiation Request play a critical role:

Capabilities

• Single and bulk payment submissions: Supports both single MPIR requests via API and bulk submissions through file uploads for high-volume payment processing.
• Automated workflows: Streamlines payment processing through automated initiation and tracking of payment statuses.

Technical requirements

• API Endpoint for single MPIR: /payto/v1/mpirs (API-based)
• Bulk submission via file: Bulk MPIR requests are processed through file uploads via sFTP, ideal for businesses handling high volumes of payment mandates.
• Authentication: Requires OAuth 2.0 with Client Credential Grant flow for secure API access. sFTP file submissions are authenticated via secure keys.
• Request Format: Payments are initiated using JSON-formatted requests for single submissions, or a structured file format for bulk submissions,.
• Security: Utilizes OAuth 2.0 bearer tokens for API access and secure sFTP communication for bulk file submissions.

Key features for developers

• Robust payment creation: Easily create and submit payment requests with required details, including beneficiary information and payment amount.
• Bulk processing: Handle large volumes of MPIRs through bulk file uploads, simplifying high-volume payment initiation.
• Status tracking: Retrieve real-time status updates on initiated payments, ensuring visibility and control over the payment lifecycle.
• Error handling: Comprehensive error responses and messages help in identifying and resolving issues promptly.

Example workflow (Single MPIR via API)

Usage notes

• Payment details: Ensure all required payment details are accurately provided in the request payload to avoid processing delays.
• Monitoring payments: Utilize the status tracking feature to monitor payment progress and handle any exceptions or rejections promptly.
• Compliance and security: Always ensure that the payment information complies with relevant regulations and security standards, using encrypted communication and verified tokens.

General Rules

• MPSUserSchemeRule1:
  • mps_user_id must be the owner of the provided mandate_identification.
• InstructedAmountSchemeRule1:
  • instructed_amount must not exceed the maximum amount specified in the associated mandate (mandate_identification).
• CreditorDetailsSchemeRule1:
  • creditor_information must be present if it is not provided in the mandate.
• CreditorDetailsSchemeRule2:
  • creditor_information should not be present if already provided on the mandate.
• CreditorDetailsSchemeRule3:
  • If creditor_information is provided and also available on the mandate, then the details must be exactly the same.