# Mamo Business API Documentation

> Mamo Business API is following the REST model. Its purpose is to enable Mamo Business users to automate the process of generating payment links and providing them to their customers. Our API accepts JSON-encoded request bodies and returns JSON-encoded responses. Standard HTTP response codes, authentication, and verbs are expected.

## API Reference
- [Quick start](https://mamopay.readme.io/reference/get_.md): Get up and running with Mamo's APIs in less than 5 minutes.<br><br>In this example, we will use the Business Details endpoint to ensure we have the right permissions to interact with Mamo's APIs.<br><br><h2>How to Use Mamo's API Docs</h2>👈 To the left, you will find all documents, including individual endpoint reference docs. These will include information on various endpoints, their associated methods and the various responses that your code will need to handle.<br><br>👉 To the right, there's the search bar, language, base URL, code generator and a <em>try it from the browser</em> section.<br>- Use the <strong>language</strong> section to select the language that you plan on writing your code in.<br>- Use the <strong>base URL</strong> to select the environment you would like the docs to target. We would recommend that you would start with the sandbox environment while you build and test your app. And later on switch to the production URL once your flows are tested and are working as expected. Hint, you need a dedicated sandbox account and API Key, if you don't have one please reach out to us using the chat bubble 💬 on the bottom right.<br>- The <strong>code generator</strong> will automatically create a working code snippet based on the values that you provide on a given page. Feel free to copy and paste this straight into your code. You can also test this using the <em>Try It!</em> button below each section. Note that for production requests, you will be required to provide a valid API Key.<br><br><h2>Payment Link Generation</h2>To generate payment links, you can follow the guide on <a href="https://mamopay.readme.io/reference/post_links">Create Payment Link</a>.<br><br>The simplest way to test your integration, is by creating a vanilla payment link that has no custom settings.<br><h2>Receive Payments On Your E-Commerce Website</h2>To make payments right on your page, code snipets can be downloaded from your dashboard<br><br><h2>FAQs</h2>- <a href="https://help.mamopay.com/en/articles/7234144-api-integrations">API Integration FAQs</a><br>- <a href="https://help.mamopay.com/en/articles/7888469-woocommerce">WooCommerce Integration Guide</a><br>- <a href="https://help.mamopay.com/en/articles/7991242-shopify">Shopify Integration Guide</a><br>- <a href="https://help.mamopay.com/en/articles/9140223-inline-payments-integration">Inline Payments Integration</a><br>
- [Authentication](https://mamopay.readme.io/reference/authentication.md)
- [Fetch Business Info](https://mamopay.readme.io/reference/get_me.md): API to fetch your business info.<br><br>
- [Fetch Account Balances](https://mamopay.readme.io/reference/get_finances.md): API to fetch the balances of the merchant's different Mamo accounts.<br><br>
- [Create Payment Link](https://mamopay.readme.io/reference/post_links.md): API to generate vanilla and subscription payment links. <br> <h3>Payment Status</h3> Once your customer completes a payment, the redirect URL will be appended with the following params<br> - createdAt: The date the charge was captured at<br> - paymentLinkId: The payment link id<br> - status: indicates the payment status, whether captured or failed<br> - transactionId: The transaction / charge id related to the payment<br> <br> You may also get notified about a payment's status by setting up a webhook. Details [here](https://mamopay.readme.io/reference/post_webhooks)<br> <br> A third approach to check the transaction status is by calling our transaction info API [here](https://mamopay.readme.io/reference/get_charges-chargeid)<br> <br> **Sample redirect url after a successful payment**<br> https://www.mamopay.com/?createdAt=2023-08-09-16-42-35&paymentLinkId=MB-LINK-3216D27C9D&status=captured&transactionId=MPB-CHRG-BEE56990A9<br> <br> <h3>For Payment Testing</h3> <p>To make payments with different use cases on the test environment, you can use the card details below alongside the below CVV and expiry date.</p> - CVV: 123<br> - Expiry: 01/28 <table> <thead> <tr> <th>Card Number</th> <th>Payment Status</th> <th>3DS</th> <th>Address Required</th> <th>Country</th> </tr> </thead> <tbody> <tr> <td>4659 1055 6905 1157</td> <td>Success</td> <td>X</td> <td>X</td> <td>GB</td> </tr> <tr> <td>4242 4242 4242 4242</td> <td>Success</td> <td>✓</td> <td>X</td> <td>GB</td> </tr> <tr> <td>4111 1111 1111 1111</td> <td>Success</td> <td>✓</td> <td>✓</td> <td>US</td> </tr> <tr> <td>4567 3613 2598 1788</td> <td>Fail</td> <td>X</td> <td>X</td> <td>GB</td> </tr> <tr> <td>4095 2548 0264 2505</td> <td>Fail</td> <td>X</td> <td>✓</td> <td>US</td> </tr> </tbody> </table>    <br> <h3>3DS</h3> If prompted for a password, enter **Checkout1!**<br> <br> <h3>Subscriptions</h3> To create a subscription payment link, create the subscription first using the [Create Subscription](/reference/post_subscriptions) API, then pass its identifier as `subscription_id` below with `link_type` set to `inline`. The inline `subscription` object is a legacy, backwards-compatible alternative — when setting it up, if both end_date and payment_quantity were defined, end_date takes precedence.<br><br>
- [Fetching Payment Links](https://mamopay.readme.io/reference/get_links.md): Fetches all payment links for a given business<br><br>
- [Update Payment Link](https://mamopay.readme.io/reference/patch_links-linkid.md): Allows a user to update payment link details<br><br>
- [Delete Payment Link](https://mamopay.readme.io/reference/delete_links-linkid.md): Allows a user to delete payment link<br><br>
- [Fetch Payment Link Info](https://mamopay.readme.io/reference/get_links-linkid.md): Allows a user to fetch payment link details<br><br>
- [Fetching Transactions](https://mamopay.readme.io/reference/get_charges.md): Fetches all transactions for a given business<br><br>
- [Initiate Payment](https://mamopay.readme.io/reference/post_charges.md): API to initiate transactions by merchant. <br> <h3>About MIT (Merchant Initiated Transaction)</h3> Merchant Initiated Transactions (MIT) allows a business to use card details, that were stored during previous transactions, to charge their customers.<br> <br> <h3>How do MITs work?</h3> 1- You request a payment link with the option to save the card details.<br> 2- You save the charge ID.<br> 3- You get the charge details (redirect, GET /charge, or webhook) which will include the ID of the card used to make the payment, you can save either one of the IDs so you always have access to the card ID.<br> 4- You call the below API to initiate a transaction using the same card.<br>
- [Fetch Transaction Info](https://mamopay.readme.io/reference/get_charges-chargeid.md): This API enables you to retrieve detailed information about a specific charge by providing the charge ID.<br>It is designed to give you a comprehensive view of transaction details.<br><br>
- [Refund Payment](https://mamopay.readme.io/reference/post_charges-chargeid-refunds.md): API to refund the charge. <br><br>
- [Capture Payment](https://mamopay.readme.io/reference/post_charges-chargeid-captures.md): API to capture an "On hold" charge. <br><br>
- [Reverse Payment](https://mamopay.readme.io/reference/post_charges-chargeid-reverses.md): API to reverse an "On hold" charge. <br><br>
- [Create Invoice](https://mamopay.readme.io/reference/post_invoices.md): API to create and send an invoice to a customer via email.
- [Create Subscription](https://mamopay.readme.io/reference/post_subscriptions.md): Creates a subscription object that defines a billing schedule (frequency, interval, start/end date, etc).<br><br> ⚠️ This API only creates the subscription object; it does not associate the subscription with a payment link. For the subscription to function correctly, the returned subscription identifier must be attached to a payment link using the `subscription_id` attribute on the [Create Payment Link](/reference/post_links) or [Update Payment Link](/reference/patch_links-linkid) APIs.<br><br>
- [Change Customer Subscription](https://mamopay.readme.io/reference/patch_subscriptions-subscriptionid-subscribers-subscriberid-change-customer-subscription.md): Upgrades a subscriber from their current subscription to a target subscription, without requiring the customer to re-enter their card details.  Prorates and charges the difference (target plan's price minus the unused remainder of the current subscription's period) against the target plan's payment link, then activates the target subscriber and unsubscribes the current one.  ### Constraints (v1)  - Only **upgrades** are supported — the target subscription's first payment amount must exceed the current subscription's prorated remaining value by at least the minimum chargeable difference. Downgrades are not yet supported and will typically fail with `PRORATION_BELOW_MINIMUM`. - The target subscription must have an **immediate start date** — you cannot change a subscriber onto a future-dated subscription. - The current and target subscriptions must use the **same currency**.  ### Error codes  | error_code | Meaning | | --- | --- | | `INACTIVE_SUBSCRIBER` | The subscriber is not active | | `MISSING_CARD` | The subscriber has no off-session chargeable card on file | | `SAME_SUBSCRIPTION` | The target subscription is the same as the subscriber's current subscription | | `PRORATION_BELOW_MINIMUM` | The prorated charge difference is below the minimum chargeable amount (2 AED / 0.55 in other currencies) | | `CHARGE_FAILED` | The proration charge was declined (includes a decline reason) |
- [Fetch Subscription Payments](https://mamopay.readme.io/reference/get_subscriptions-subscriptionid-payments.md): Fetches all subscription payments made against a Subscription item. Developers should use the customer's email address to filter out payments made by a single customer. The creation date can be used to decide whether a customer should be kept on the same plan or downgraded to a lower / free one.
- [Fetch Subscribers](https://mamopay.readme.io/reference/get_subscriptions-subscriptionid-subscribers.md): Fetches all subscribers of subscription.<br><br>
- [Unsubscribe subscription](https://mamopay.readme.io/reference/delete_subscriptions-subscriptionid-subscribers-subscriberid.md): Unsubscribe subscription.<br><br>
- [Cancel Subscription](https://mamopay.readme.io/reference/delete_subscriptions-subscriptionid.md): Cancels an existing subscription. This is NOT to unsubscribe a customer from a subscription that they have subscribed to. This deletes a previously created subscription for a business. <br><br>
- [Issue Disbursements](https://mamopay.readme.io/reference/post_disbursements.md): Allows the issuance of disbursements in bulk<br><br>
- [Fetch Disbursement Info](https://mamopay.readme.io/reference/get_disbursements-disbursementid.md): Allows a user to fetch the disbursement details.<br><br>
- [Create Recipient](https://mamopay.readme.io/reference/post_accounts-recipients.md): Allows a user to create recipient.<br><br>
- [Fetching Recipients](https://mamopay.readme.io/reference/get_accounts-recipients.md): Fetches all recipients for a given business.<br><br>
- [Update Recipient](https://mamopay.readme.io/reference/patch_accounts-recipients-recipientidentifier.md): Allows a user to update recipient details.<br><br>
- [Delete Recipient](https://mamopay.readme.io/reference/delete_accounts-recipients-recipientidentifier.md): Allows a user to delete recipient.<br><br>
- [Fetch Recipient](https://mamopay.readme.io/reference/get_accounts-recipients-recipientidentifier.md): Allows a user to fetch recipient details.<br><br>
- [Create Partner Card](https://mamopay.readme.io/reference/post_partner-cards.md): Create a partner card for business transactions. This API allows you to issue virtual cards with specific limits and controls for your business partners. This API is available upon request for a tailored integration. Email us on api@mamopay.com to get started.
- [Get Partner Cards List](https://mamopay.readme.io/reference/get_partner-cards.md): Retrieve a paginated list of all partner cards for the business. This endpoint allows you to view all issued partner cards with their current status and details.
- [Get Partner Card Details](https://mamopay.readme.io/reference/get_partner-cards-identifier.md): Retrieve detailed information about a specific partner card using its identifier. This endpoint provides complete card information including current status, spending details, and metadata.
- [Update Partner Card](https://mamopay.readme.io/reference/patch_partner-cards-identifier.md): Update the amount limit of an active partner card. This allows you to increase or decrease the spending limit on the card. Only active cards can be updated.
- [Cancel Partner Card](https://mamopay.readme.io/reference/patch_partner-cards-identifier-cancel.md): Cancel an active partner card. This action will terminate the card and prevent any further transactions. Only active cards can be cancelled.
- [Get Partner Card Transactions](https://mamopay.readme.io/reference/get_partner-cards-identifier-transactions.md): Retrieve a paginated list of all transactions for a specific partner card. This endpoint provides detailed transaction history including purchase information, amounts, and status.
- [Get Partner Card Transaction Details](https://mamopay.readme.io/reference/get_partner-cards-identifier-transactions-transaction-identifier.md): Retrieve detailed information about a specific transaction for a partner card. This endpoint provides complete transaction details including merchant information, amounts, and status.
- [Fetching Card Transactions](https://mamopay.readme.io/reference/get_cards-transactions.md): Fetches all transactions for cards<br><br>
- [Fetch Transaction Details](https://mamopay.readme.io/reference/get_cards-transactions-transactionid.md): Fetches detailed information for a specific card transaction<br><br>
- [Update Expense](https://mamopay.readme.io/reference/patch_expenses-expenseid.md): Updates expense details such as description, invoice number, and status
- [Fetching Expense Receipts](https://mamopay.readme.io/reference/get_expenses-receipts.md): Fetches all expense receipts for a given business<br><br>
- [Fetch Expense Receipt Details](https://mamopay.readme.io/reference/get_expenses-receipts-identifier.md): Fetches detailed information for a specific expense receipt<br><br>
- [Create Webhook](https://mamopay.readme.io/reference/post_webhooks.md): Webhook registration for updates on one-off payment statuses and subscription payment statues.<br><br>
- [Fetching Webhooks](https://mamopay.readme.io/reference/get_webhooks.md): Fetches all registered webhooks for a given business.<br><br>
- [Update Webhook](https://mamopay.readme.io/reference/patch_webhooks-webhookid.md): Allows a user to update webhook details.<br><br>
- [Delete Webhook](https://mamopay.readme.io/reference/delete_webhooks-webhookid.md): Allows a user to delete a registered webhook.<br><br>
- [Charge Object](https://mamopay.readme.io/reference/charge-object.md)
- [Payment Link Object](https://mamopay.readme.io/reference/payment-link-object.md)
- [Payout Object](https://mamopay.readme.io/reference/payout-object.md)
- [Transaction Object](https://mamopay.readme.io/reference/transaction-object.md)
- [Expense Object](https://mamopay.readme.io/reference/expense-object.md)
- [Subscription Object](https://mamopay.readme.io/reference/subscription-object.md)
- [Failure messages](https://mamopay.readme.io/reference/transaction-failure-messages.md): These are the failure messages of payment:
- [Changelog](https://mamopay.readme.io/reference/changelog.md)