API Migration Guide: Transitioning to API Gateway
Overview
This document provides the necessary steps to migrate your existing integration to our new API. The transition is straightforward, as the new version maintains 100% feature parity with the old API's. While the data structures and logic remain identical, this migration involves a shift to our new infrastructure and updated endpoints.
1. Prerequisites (Action Required)
Before you can begin updating your endpoints, you must register your application in our new environment:
đą
Partner's Portal Registration
Access to the new API is managed through our Partner's Portal. You will need to create an account and register your integration there to obtain new credentials.
Register here âđ
Onboarding Guide
For a step-by-step walkthrough on how to register and set up your new integration, please visit our documentation.
View Onboarding Documentation â2. What is Changing?
The core data logic remains the same, but the integration workflow and authentication process have been updated as follows:
A Merchant Authorization Workflow
To connect with a merchant, you must now follow these steps within the Partner Portal:
1.
Share Approval Link
After creating your integration, you will receive a unique share link. You must send this link to the merchant for their formal approval.
2.
Merchant Approval
The merchant must approve the integration through the link before you can proceed to generate credentials.
B Credential Management
1.
Once the merchant has approved the integration, navigate to the Merchants tab in the portal.
2.
Generate Merchant Credentials
You can then generate the Merchant Client ID and Merchant Client Secret.
â ī¸
Important
The Merchant Secret is displayed only once. Ensure you store it securely immediately.
C Updated Authentication (Token Generation)
The new API uses a multi-layer security approach to generate session access:
1.
Bearer Token
Use your Partner Client ID and Partner Secret to request a Bearer Token.
2.
Session ID
Generate a Session ID by providing the Merchant ID, Merchant Secret, and the Bearer Token obtained in the previous step.
D Endpoint Mapping
All legacy endpoints must be pointed to the new Base URL:
While request and response schemas remain identical to the previous version, you must update the specific paths. A detailed mapping table for all endpoints is provided in the following section of this guide.
đĄ
Note
Please verify the request formats in the documentation, as there may be subtle differences between the APIs.
3. API Mapping Table
Below is a detailed list of the legacy APIs and their corresponding endpoints in the new API Gateway. Please ensure you update both the Base URL and the specific path for each request.
A. Transaction API Mapping
| Old APIs | New APIs |
|---|---|
| Transaction API | API Gateway - Banking |
| List Transactions | Get Merchants Transactions List |
| Transaction Details | Get Merchant Transaction Details based on Payment Reference |
| Multiple Transaction Details | Get Multiple Merchant Transactions Details based on Payment References |
| List Accounts | Get Merchant Accounts - related to the input session |
| Generate MT940 Statement | Generate Account Statement File based on input Date |
âšī¸
The integration type in the Partner's portal must be Account management.
B. Transaction API â API Gateway - Ecommerce
| Old APIs | New APIs |
|---|---|
| Transaction API | API Gateway - Ecommerce |
| Create Payment Button | Create Payment Button |
| Create Payment Link | Create Payment Link |
| Languages | List of Languages |
| List Payment Buttons | List of Payment Buttons |
| List Payment Links | List of Payment Links |
| Payment Button Details | Payment Button Details |
| Payment Link Details | Receive Payment Link Details by code |
| Delete Payment Button | Delete Payment Button |
| Delete Payment Link | Delete Payment Link |
| Settlement Data | Settlement Data |
| Edit Payment Button | Update details of Payment Button |
| Edit Payment Link | Edit Payment Link details |
| Create Payment Request | Create Payment Request |
| Send Payment Request reminder | Send Payment Request reminder |
| List Payment Requests | List Payment Requests |
| Payment Request Details | Payment Request Details |
âšī¸
The integration type in the Partner's portal must be Ecommerce.
C. Devices API â API Gateway â POS
| Old APIs | New APIs |
|---|---|
| Devices API | API Gateway - POS |
| List Devices | Get Terminals |
| List Transactions | Get All Transactions |
| Device Details | Get Terminals Details |
| Receipt Details | Get Terminal Receipt By Payment Reference |
| List Device Transactions | Get Terminal Transactions by Id |
| Refund | Terminal Refund |
âšī¸
The integration type in the Partner's portal must be Cash Register.
Final Checklist for Developers
â
Replace your legacy Base URL with
https://api-gateway.mypos.com/.â
Update the endpoint paths as shown in the tables above.
â
Important: Double-check the request body parameters for each "New API" endpoint in our official documentation, as minor schema updates may have been applied.