Mamo Cards API

openapi: 3.0.0
info:
  title: Mamo Business Business Details Cards 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: Cards
paths:
  /partner_cards/{identifier}/transactions/{transaction_identifier}:
    get:
      tags:
      - Cards
      summary: Get Partner Card Transaction Details
      description: Retrieve detailed information about a specific transaction for a partner card. This endpoint provides complete transaction details including merchant information, amounts, and status.
      parameters:
      - in: path
        name: identifier
        schema:
          type: string
        required: true
        description: Unique identifier of the partner card
        example: CRD-5959837C07
      - in: path
        name: transaction_identifier
        schema:
          type: string
        required: true
        description: Unique identifier of the transaction
        example: CTX-1A95FEDE53
      - 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:
                  kind:
                    type: string
                    description: Type of transaction
                    enum:
                    - purchase
                    - refund
                    - authorization
                  merchant_name_formatted:
                    type: string
                    description: Formatted merchant name for display
                  amount_currency:
                    type: string
                    description: Currency code for the transaction amount
                  billing_amount_currency:
                    type: string
                    description: Currency code for the billing amount
                  status:
                    type: string
                    description: Transaction status
                    enum:
                    - success
                    - failed
                    - pending
                  card_last4:
                    type: string
                    description: Last 4 digits of the card used
                  id:
                    type: string
                    description: Unique transaction identifier
                  merchant_name:
                    type: string
                    description: Raw merchant name
                  amount:
                    type: number
                    description: Transaction amount
                  billing_amount:
                    type: number
                    description: Billing amount
                  card_name:
                    type: string
                    description: Name of the card
                  card_holder_name:
                    type: string
                    description: Name of the card holder
                  created_at:
                    type: string
                    description: Transaction creation date and time
                  updated_at:
                    type: string
                    description: Transaction last update date and time
                  expense:
                    type: object
                    description: Associated expense information
                example:
                  kind: purchase
                  merchant_name_formatted: Virtual card issued
                  amount_currency: AED
                  billing_amount_currency: AED
                  status: success
                  card_last4: '5737'
                  id: CTX-1A95FEDE53
                  merchant_name: null
                  amount: 200
                  billing_amount: 200
                  card_name: VCC card
                  card_holder_name: MCS integration
                  created_at: 15 Dec 2025, 08:26AM
                  updated_at: 15 Dec 2025, 08:26AM
                  expense: {}
        '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: Transaction or card not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Transaction not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: getPartnerCardsIdentifierTransactionsTransactionIdentifier
  /partner_cards/{identifier}/transactions:
    get:
      tags:
      - Cards
      summary: Get Partner Card Transactions
      description: Retrieve a paginated list of all transactions for a specific partner card. This endpoint provides detailed transaction history including purchase information, amounts, and status.
      parameters:
      - in: path
        name: identifier
        schema:
          type: string
        required: true
        description: Unique identifier of the partner card
        example: CRD-5959837C07
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: Page number for pagination
        example: 1
      - in: query
        name: per_page
        schema:
          type: integer
          default: 10
        description: Number of items per page
        example: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                          description: Type of transaction
                          enum:
                          - purchase
                          - refund
                          - authorization
                        merchant_name_formatted:
                          type: string
                          description: Formatted merchant name for display
                        amount_currency:
                          type: string
                          description: Currency code for the transaction amount
                        billing_amount_currency:
                          type: string
                          description: Currency code for the billing amount
                        status:
                          type: string
                          description: Transaction status
                          enum:
                          - success
                          - failed
                          - pending
                        card_last4:
                          type: string
                          description: Last 4 digits of the card used
                        id:
                          type: string
                          description: Unique transaction identifier
                        merchant_name:
                          type: string
                          description: Raw merchant name
                        amount:
                          type: number
                          description: Transaction amount
                        billing_amount:
                          type: number
                          description: Billing amount
                        card_name:
                          type: string
                          description: Name of the card
                        card_holder_name:
                          type: string
                          description: Name of the card holder
                        created_at:
                          type: string
                          description: Transaction creation date and time
                        updated_at:
                          type: string
                          description: Transaction last update date and time
                        expense:
                          type: object
                          description: Associated expense information
                  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:
                  - kind: purchase
                    merchant_name_formatted: Virtual card issued
                    amount_currency: AED
                    billing_amount_currency: AED
                    status: success
                    card_last4: '5737'
                    id: CTX-1A95FEDE53
                    merchant_name: null
                    amount: 200
                    billing_amount: 200
                    card_name: VCC card
                    card_holder_name: MCS integration
                    created_at: 15 Dec 2025, 08:26AM
                    updated_at: 15 Dec 2025, 08:26AM
                    expense: {}
                  pagination_meta:
                    page: 1
                    per_page: 10
                    total_pages: 1
                    next_page: null
                    prev_page: null
                    from: 1
                    to: 1
                    total_count: 1
        '403':
          description: Unauthorised
        '404':
          description: Card not found
        '500':
          description: Unexpected error
      operationId: getPartnerCardsIdentifierTransactions
  /partner_cards/{identifier}:
    get:
      tags:
      - Cards
      summary: Get Partner Card Details
      description: Retrieve detailed information about a specific partner card using its identifier. This endpoint provides complete card information including current status, spending details, and metadata.
      parameters:
      - in: path
        name: identifier
        schema:
          type: string
        required: true
        description: Unique identifier of the partner card
        example: CRD-5959837C07
      - 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:
                  cardHolderName:
                    type: string
                    description: Name of the card holder
                  expiryDate:
                    type: string
                    description: Card expiry date in MM/YY format
                  cardLast4:
                    type: string
                    description: Last 4 digits of the card number
                  status:
                    type: string
                    description: Current status of the card
                    enum:
                    - active
                    - inactive
                    - expired
                    - terminated
                  bookingId:
                    type: string
                    description: Booking reference associated with the card
                  createdAt:
                    type: string
                    format: date-time
                    description: Card creation timestamp
                  updatedAt:
                    type: string
                    format: date-time
                    description: Card last update timestamp
                  id:
                    type: string
                    description: Unique card identifier
                  amount:
                    type: number
                    description: Card amount limit
                  totalSpend:
                    type: number
                    description: Total amount spent on the card
                example:
                  cardHolderName: MCS integration
                  expiryDate: 12/28
                  cardLast4: '5737'
                  status: active
                  bookingId: Testing1235821444579867
                  createdAt: '2025-12-15T08:22:11.930+04:00'
                  updatedAt: '2025-12-15T08:22:15.071+04:00'
                  id: CRD-5959837C07
                  amount: 500
                  totalSpend: 200
        '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: Card not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Partner card not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: getPartnerCardsIdentifier
    patch:
      tags:
      - Cards
      summary: Update Partner Card
      description: 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.
      parameters:
      - in: path
        name: identifier
        schema:
          type: string
        required: true
        description: Unique identifier of the partner card to update
        example: CRD-5959837C07
      - 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:
                amount:
                  type: number
                  description: New amount limit for the card
                  minimum: 1
              required:
              - amount
              example:
                amount: 500
      responses:
        '200':
          description: Card updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the update was successful
                example:
                  success: true
        '400':
          description: Bad Request - Card cannot be updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Only active cards can be updated
                  error_code: INVALID_CARD_STATUS
        '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: Card not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Partner card not found
                  error_code: RECORD_NOT_FOUND
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Amount must be greater than 0
                  error_code: VALIDATION_FAILED
        '500':
          description: Unexpected error
      operationId: patchPartnerCardsIdentifier
  /partner_cards:
    get:
      tags:
      - Cards
      summary: Get Partner Cards List
      description: 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.
      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>
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: Page number for pagination
        example: 1
      - in: query
        name: per_page
        schema:
          type: integer
          default: 10
        description: Number of items per page
        example: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        card_holder_name:
                          type: string
                          description: Name of the card holder
                        expiry_date:
                          type: string
                          description: Card expiry date in MM/YY format
                        card_last4:
                          type: string
                          description: Last 4 digits of the card number
                        status:
                          type: string
                          description: Current status of the card
                          enum:
                          - active
                          - inactive
                          - expired
                          - terminated
                        booking_id:
                          type: string
                          description: Booking reference associated with the card
                        created_at:
                          type: string
                          format: date-time
                          description: Card creation timestamp
                        updated_at:
                          type: string
                          format: date-time
                          description: Card last update timestamp
                        id:
                          type: string
                          description: Unique card identifier
                        amount:
                          type: number
                          description: Card amount limit
                        total_spend:
                          type: number
                          description: Total amount spent on the card
                  pagination_meta:
                    type: object
                    properties:
                      page:
                        type: number
                        description: Current page number
                      per_page:
                        type: number
                        description: Number of items per page
                      total_pages:
                        type: number
                        description: Total number of pages
                      next_page:
                        type: number
                        description: Next page number (null if last page)
                      prev_page:
                        type: number
                        description: Previous page number (null if first page)
                      from:
                        type: number
                        description: Starting item number on current page
                      to:
                        type: number
                        description: Ending item number on current page
                      total_count:
                        type: number
                        description: Total number of items across all pages
                example:
                  data:
                  - card_holder_name: MCS integration
                    expiry_date: 12/28
                    card_last4: '9623'
                    status: active
                    booking_id: Testing12345
                    created_at: '2025-12-15T08:41:37.781+04:00'
                    updated_at: '2025-12-15T08:54:20.946+04:00'
                    id: CRD-E03E386695
                    amount: 500
                    total_spend: 0
                  - card_holder_name: MCS integration
                    expiry_date: 12/28
                    card_last4: '5737'
                    status: terminated
                    booking_id: Testing1235821444579867
                    created_at: '2025-12-15T08:22:11.930+04:00'
                    updated_at: '2025-12-15T08:30:54.057+04:00'
                    id: CRD-5959837C07
                    amount: 500
                    total_spend: 200
                  pagination_meta:
                    page: 1
                    per_page: 10
                    total_pages: 2
                    next_page: 2
                    prev_page: null
                    from: 1
                    to: 10
                    total_count: 19
        '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: getPartnerCards
    post:
      tags:
      - Cards
      summary: Create Partner Card
      description: 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.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: The amount limit for the partner card.
                email:
                  type: string
                  description: Cardholder’s email address. Card holder must have completed KYC.
                booking_id:
                  type: string
                  description: Booking reference in case the card will be used for a 1 time booking.
                verification_email:
                  type: string
                  format: email
                  description: The email address that will be used for verification purposes.
                transactions_limit:
                  type: number
                  description: Maximum number of transactions allowed on the card.
              required:
              - amount
              - email
              - booking_id
              - verification_email
              - transactions_limit
              example:
                amount: 2000
                email: phu+349@mamopay.com
                booking_id: Testing1235821444579867
                verification_email: phu@mamopay.com
                transactions_limit: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  card_holder_name:
                    type: string
                    description: Name of the card holder
                  expiry_date:
                    type: string
                    description: Card expiry date in MM/YY format
                  card_last4:
                    type: string
                    description: Last 4 digits of the card number
                  status:
                    type: string
                    description: Current status of the card
                    enum:
                    - active
                    - inactive
                    - expired
                  booking_id:
                    type: string
                    description: Booking reference associated with the card
                  created_at:
                    type: string
                    format: date-time
                    description: Card creation timestamp
                  updated_at:
                    type: string
                    format: date-time
                    description: Card last update timestamp
                  id:
                    type: string
                    description: Unique card identifier
                  amount:
                    type: number
                    description: Card amount limit
                  total_spend:
                    type: number
                    description: Total amount spent on the card
                  url:
                    type: string
                    description: URL to access the card details with authentication token
                example:
                  card_holder_name: MCS integration
                  expiry_date: 12/28
                  card_last4: 0379
                  status: active
                  booking_id: Testing1235821444579867
                  created_at: '2025-12-15T08:09:25.167+04:00'
                  updated_at: '2025-12-15T08:09:28.271+04:00'
                  id: CRD-F08AA9522C
                  amount: 2000
                  total_spend: 0
                  url: https://sandbox.dev.business.mamopay.com/cards/vcc?token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJtYW1vcGF5LXZjYy10b2tlbiIsImF1ZCI6Im1hbW9wYXktYXBpLXNlcnZlciIsImlhdCI6MTc2NTc3MTc2OCwic3ViIjoiQ1JELUYwOEFBOTUyMkMiLCJleHAiOjE3ODEzMjM3Njh9.u7ENYVa5M0LzppG7CwaJl57Ps2gPCnmVWiziR2K4WSw
        '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:
                  - See errors
                  error_code: VALIDATION_FAILED
                  errors:
                  - User doesn't exist
        '500':
          description: Unexpected error
      operationId: postPartnerCards
  /partner_cards/{identifier}/cancel:
    patch:
      tags:
      - Cards
      summary: Cancel Partner Card
      description: Cancel an active partner card. This action will terminate the card and prevent any further transactions. Only active cards can be cancelled.
      parameters:
      - in: path
        name: identifier
        schema:
          type: string
        required: true
        description: Unique identifier of the partner card to cancel
        example: CRD-5959837C07
      - 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: Card cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the cancellation was successful
                example:
                  success: true
        '400':
          description: Bad Request - Card cannot be cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Only active cards can be cancelled
                  error_code: INVALID_CARD_STATUS
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
         

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mamo/refs/heads/main/openapi/mamo-cards-api-openapi.yml