Mamo Recipients API

openapi: 3.0.0
info:
  title: Mamo Business Business Details Recipients API
  version: '1.6'
  description: Mamo Business API follows the REST model. Its purpose is to enable Mamo Business users to automate payment link generation, charges, subscriptions, disbursements, recipients, cards, expenses and webhooks. Accepts JSON request bodies and returns JSON responses.
  contact:
    name: Mamo API Support
    email: api@mamopay.com
servers:
- url: https://business.mamopay.com/manage_api/v1
  description: Production server
- url: https://sandbox.dev.business.mamopay.com/manage_api/v1
  description: Sandbox server
security:
- bearerAuth: []
tags:
- name: Recipients
paths:
  /accounts/recipients/{recipientIdentifier}:
    delete:
      tags:
      - Recipients
      summary: Delete Recipient
      description: Allows a user to delete recipient.<br><br>
      parameters:
      - in: path
        name: recipientIdentifier
        schema:
          type: string
          default: REP-6BB7CA8DC7
        required: true
        description: Recipient Identifier
        example: REP-6BB7CA8DC7
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                example:
                  success: true
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Invalid request
        '500':
          description: Unexpected error
      operationId: deleteAccountsRecipientsRecipientidentifier
    get:
      tags:
      - Recipients
      summary: Fetch Recipient
      description: Allows a user to fetch recipient details.<br><br>
      parameters:
      - in: path
        name: recipientIdentifier
        schema:
          type: string
          default: REP-6BB7CA8DC7
        required: true
        description: Recipient Identifier
        example: REP-6BB7CA8DC7
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                  recipient_type:
                    type: string
                  name:
                    type: string
                  relationship:
                    type: string
                  email:
                    type: string
                  eid_number:
                    type: string
                  reason:
                    type: string
                  address:
                    type: object
                    properties:
                      address_line1:
                        type: string
                      address_line2:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                  bank:
                    type: object
                    properties:
                      iban:
                        type: string
                      account_number:
                        type: string
                      name:
                        type: string
                      bic_code:
                        type: string
                      address:
                        type: string
                      country:
                        type: string
                  created_at:
                    type: string
                  recipient_meta:
                    type: object
                example:
                  identifier: REP-D8B07FB8C7
                  name: first name last name
                  recipient_type: individual
                  relationship: others
                  reason: reason
                  email: null
                  eid_number: null
                  address: null
                  bank:
                    iban: AE080200000123223333121
                    country: AE
                    name: null
                    account_number: null
                    address: null
                    city: null
                    bic_code: null
                  created_at: 19/02/2024
                  recipient_meta: {}
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Merchant::Recipient record was not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: getAccountsRecipientsRecipientidentifier
    patch:
      tags:
      - Recipients
      summary: Update Recipient
      description: Allows a user to update recipient details.<br><br>
      parameters:
      - in: path
        name: recipientIdentifier
        schema:
          type: string
          default: REP-6BB7CA8DC7
        required: true
        description: Recipient Identifier
        example: REP-6BB7CA8DC7
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient_type:
                  type: string
                  enum:
                  - individual
                  - business
                  description: The type of the recipient.
                  default: individual
                email:
                  type: string
                  description: Recipient's email.
                business_name:
                  type: string
                  description: Name of the recipient when recipient_type is business.
                first_name:
                  type: string
                  description: First name of the recipient when recipient_type is individual.
                last_name:
                  type: string
                  description: Last name of the recipient when recipient_type is individual.
                relationship:
                  type: string
                  enum:
                  - business_associate_partner
                  - customer
                  - employee
                  - branch_representative_office
                  - subsidiary_company
                  - holding_company
                  - supplier
                  - creditor
                  - debtor
                  - franchisee_franchisor
                  - others
                  description: Recipient's relationship
                reason:
                  type: string
                  description: Reason for the payouts issued to this recipient.
                eid_number:
                  type: string
                  description: Recipient's Emirates ID number.
                bank:
                  type: object
                  properties:
                    iban:
                      type: string
                      description: Recipient's IBAN.
                      default: AE080200000123223333121
                    account_number:
                      type: string
                      description: Recipient's bank account number (only iban or account_number is required)
                    address:
                      type: string
                      description: Recipient's bank address.
                    country:
                      type: string
                      description: Recipient's bank country (two letters ISO country code).
                      default: AE
                    name:
                      type: string
                      description: Recipient's bank name.
                    bic_code:
                      type: string
                      description: Recipient's bank identifier codes for non UAE bank.
                address:
                  type: object
                  properties:
                    address_line1:
                      type: string
                      description: Recipient's first line of the address.
                    address_line2:
                      type: string
                      description: Recipient's second line of the address.
                    city:
                      type: string
                      description: Recipient's city.
                    state:
                      type: string
                      description: 'The state or province of the address in ISO 3166-2 (for example: CA for California in the United States).'
                    country:
                      type: string
                      description: Recipient's address country (two letters ISO country code).
                recipient_meta:
                  type: object
              example:
                recipient_type: individual
                first_name: first name
                last_name: last name
                relationship: others
                reason: reason
                bank:
                  iban: AE080200000123223333121
                  country: AE
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                  recipient_type:
                    type: string
                  name:
                    type: string
                  relationship:
                    type: string
                  email:
                    type: string
                  eid_number:
                    type: string
                  reason:
                    type: string
                  address:
                    type: object
                    properties:
                      address_line1:
                        type: string
                      address_line2:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                  bank:
                    type: object
                    properties:
                      iban:
                        type: string
                      account_number:
                        type: string
                      name:
                        type: string
                      bic_code:
                        type: string
                      address:
                        type: string
                      country:
                        type: string
                  created_at:
                    type: string
                  recipient_meta:
                    type: object
                example:
                  identifier: REP-D8B07FB8C7
                  name: first name last name
                  recipient_type: individual
                  relationship: others
                  reason: reason
                  email: null
                  eid_number: null
                  address: null
                  bank:
                    iban: AE080200000123223333121
                    country: AE
                    name: null
                    account_number: null
                    address: null
                    city: null
                    bic_code: null
                  created_at: 19/02/2024
                  recipient_meta: {}
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Merchant::Recipient record was not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: patchAccountsRecipientsRecipientidentifier
  /accounts/recipients:
    get:
      tags:
      - Recipients
      summary: Fetching Recipients
      description: Fetches all recipients for a given business.<br><br>
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        identifier:
                          type: string
                        recipient_type:
                          type: string
                        name:
                          type: string
                        relationship:
                          type: string
                        email:
                          type: string
                        eid_number:
                          type: string
                        reason:
                          type: string
                        address:
                          type: object
                          properties:
                            address_line1:
                              type: string
                            address_line2:
                              type: string
                            city:
                              type: string
                            state:
                              type: string
                            country:
                              type: string
                        bank:
                          type: object
                          properties:
                            iban:
                              type: string
                            account_number:
                              type: string
                            name:
                              type: string
                            bic_code:
                              type: string
                            address:
                              type: string
                            country:
                              type: string
                        created_at:
                          type: string
                        recipient_meta:
                          type: object
                  pagination_meta:
                    type: object
                    properties:
                      page:
                        type: number
                      per_page:
                        type: number
                      total_pages:
                        type: number
                      next_page:
                        type: number
                      prev_page:
                        type: number
                      from:
                        type: number
                      to:
                        type: number
                      total_count:
                        type: number
                example:
                  data:
                  - identifier: REP-D8B07FB8C7
                    name: first name last name
                    recipient_type: individual
                    relationship: others
                    reason: reason
                    email: null
                    eid_number: null
                    address: null
                    bank:
                      iban: AE080200000123223333121
                      country: AE
                      name: null
                      account_number: null
                      address: null
                      city: null
                      bic_code: null
                    created_at: 19/02/2024
                    recipient_meta: {}
                  pagination_meta:
                    page: 1
                    per_page: 10
                    total_pages: 5
                    next_page: 2
                    prev_page: null
                    from: 1
                    to: 10
                    total_count: 47
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '500':
          description: Unexpected error
      operationId: getAccountsRecipients
    post:
      tags:
      - Recipients
      summary: Create Recipient
      description: Allows a user to create recipient.<br><br>
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient_type:
                  type: string
                  enum:
                  - individual
                  - business
                  description: The type of the recipient.
                  default: individual
                email:
                  type: string
                  description: Recipient's email.
                business_name:
                  type: string
                  description: Name of the recipient when recipient_type is business.
                first_name:
                  type: string
                  description: First name of the recipient when recipient_type is individual.
                last_name:
                  type: string
                  description: Last name of the recipient when recipient_type is individual.
                relationship:
                  type: string
                  enum:
                  - business_associate_partner
                  - customer
                  - employee
                  - branch_representative_office
                  - subsidiary_company
                  - holding_company
                  - supplier
                  - creditor
                  - debtor
                  - franchisee_franchisor
                  - others
                  description: Recipient's relationship
                reason:
                  type: string
                  description: Reason for the payouts issued to this recipient.
                eid_number:
                  type: string
                  description: Recipient's Emirates ID number.
                bank:
                  type: object
                  properties:
                    iban:
                      type: string
                      description: Recipient's IBAN.
                      default: AE080200000123223333121
                    account_number:
                      type: string
                      description: Recipient's bank account number (only iban or account_number is required)
                    address:
                      type: string
                      description: Recipient's bank address.
                    country:
                      type: string
                      description: Recipient's bank country (two letters ISO country code).
                      default: AE
                    name:
                      type: string
                      description: Recipient's bank name.
                    bic_code:
                      type: string
                      description: Recipient's bank identifier codes for non UAE bank.
                address:
                  type: object
                  properties:
                    address_line1:
                      type: string
                      description: Recipient's first line of the address.
                    address_line2:
                      type: string
                      description: Recipient's second line of the address.
                    city:
                      type: string
                      description: Recipient's city.
                    state:
                      type: string
                      description: 'The state or province of the address in ISO 3166-2 (for example: CA for California in the United States).'
                    country:
                      type: string
                      description: Recipient's address country (two letters ISO country code).
                recipient_meta:
                  type: object
              required:
              - recipient_type
              - reason
              - relationship
              - bank
              example:
                recipient_type: individual
                first_name: first name
                last_name: last name
                relationship: others
                reason: reason
                bank:
                  iban: AE080200000123223333121
                  country: AE
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                  recipient_type:
                    type: string
                  name:
                    type: string
                  relationship:
                    type: string
                  email:
                    type: string
                  eid_number:
                    type: string
                  reason:
                    type: string
                  address:
                    type: object
                    properties:
                      address_line1:
                        type: string
                      address_line2:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      province:
                        type: string
                      zip:
                        type: string
                      country:
                        type: string
                  bank:
                    type: object
                    properties:
                      iban:
                        type: string
                      account_number:
                        type: string
                      name:
                        type: string
                      bic_code:
                        type: string
                      address:
                        type: string
                      country:
                        type: string
                  created_at:
                    type: string
                  recipient_meta:
                    type: object
                example:
                  identifier: REP-081BCADE9A
                  email: null
                  eid_number: null
                  recipient_type: individual
                  relationship: others
                  recipient_meta: null
                  name: Test User
                  created_at: 04/12/2025
                  bank:
                    name: null
                    address: null
                    country: AE
                    iban: AE080200000123223333121
                    account_number: null
                    bic_code: null
                  address:
                    address_line1: null
                    address_line2: null
                    city: null
                    state: null
                    province: null
                    zip: null
                    country: null
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Invalid request
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                  error_code:
                    type: string
                  errors:
                    type: object
                    properties:
                      name:
                        type: array
                        items:
                          type: string
                example:
                  messages:
                  - First name can't be blank
                  error_code: VALIDATION_FAILED
                  errors:
                    first_name:
                    - can't be blank
        '500':
          description: Unexpected error
      operationId: postAccountsRecipients
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from the Mamo dashboard (Developer > Keys), passed as `Authorization: Bearer <api_key>`.'