DOCSEARCHbyAlgolia
Submit Docs

Altpay Documentation

website·Indexed 31 days ago

https://docs.altpay.dev/

Developer documentation for Altpay payment integration, featuring APIs for Tag-QR payments, cash deposits, wallet management, OTP-based payments, and refund processing. Includes endpoints for payment status tracking, balance inquiries, and user/company management.

Tokens
20.5K
Snippets
98
Records
138
Agent score
49%

What's inside Altpay

  1. Overview of Tap Card functionality

    Tap Card allows wallet users to make payments and gain access using a physical card. Each card is linked to a specific wallet user via a user_mapping_id. Expenses made with the card are deducted from that user's wallet. A single user can have multiple cards assigned to them, which can be distinguished using the name field. The system provides three primary services: card definition (assignment), card listing, and card cancellation.

  3. Retrieve user details by phone number

    Use this endpoint to get information about a user associated with a specific phone number. This service is primarily used to determine the current state of a user and decide which subsequent action to take (registration or linking).

    User State Logic:

    • non_registered (404 Response): The phone number is not registered in Macellan SuperApp. Action: Perform OTP verification and call the Register service.
    • registered_but_non_linked (200 Response): The user is registered in SuperApp but not linked to the wallet. User details (name, email) will be masked. Action: Perform OTP verification and call the Linking service.
    • linked (200 Response): The user is successfully linked. User details are provided without masking.
    # Request
GET /waas/integration/users/by-phone/{phone}

# Example phone parameter (E.164 Format)
# /waas/integration/users/by-phone/905231113344

  4. Understand Macellan SuperApp payment flows

    There are two primary payment flows using the digital wallet:

    1. User-Generated QR: The user creates a QR code containing a 6-digit reference code. The integrator scans this QR or uses the code to send the amount to the service. The user then approves the payment in the app.
    2. Integrator-Generated QR: The integrator sends the amount to the service and receives a reference code to generate a QR. The user scans this QR or enters the 6-digit code in the app to approve the payment.

    In both flows, the integrator must poll the service to check the payment status and finalize the transaction.

  5. Handle Cash Deposit Refund Webhooks

    The cashDepositRefund webhook is triggered after a cash deposit refund operation is performed on company wallets. It provides detailed information about the user, the refund amounts, and the specific cash deposits being refunded.
    {
    "event": "cashDepositRefund",
    "user": {
        "id": 1,
        "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
        "region": "TR",
        "locale": "tr",
        "first_name": "Macellan",
        "last_name": "Superapp",
        "full_name": "Macellan SuperApp",
        "email": "altdev@macellan.net",
        "phone": 905231113344,
        "details": {
          "subscribe_sms": false,
          "subscribe_email": false,
          "gender": "male",
          "id_number": 11111111111
        }
    },
    "waas_user_mapping": {
        "id": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
        "is_active": true,
        "created_at": "timestamp"
    },
    "data": {
        "id": 1,
        "status": "refund",
        "instant_wallet_balance": 1,
        "instant_wallet_point": 1,
        "balance": 1,
        "point": 1,
        "point_spent": 1,
        "deposit_amount": 1,
        "earned_point_amount": 1,
        "refund_amount": 1,
        "cash_deposits": [
            {
                "id": 1,
                "gateway": "terminal", // [terminal, static_qr, box_office, kiosk]
                "method": "cash", // [cash, credit_card]
                "amount": 1,
                "reference_code": 952340,
                "order_id": 95234,
                "created_at": "timestamp",
                "branch": {
                    "id": 1,
                    "name": "İstanbul",
                    "allow_point_usage": true,
                    "phone": "+905231113344",
                    "code": "12345",
                    "description": "İstanbul şubesi"
                },
                "refund_amount": 0,
                "rest_amount": 0,
                "completed_at": "timestamp"
            }
        ],
        "created_at": "timestamp",
        "reason": "wrong_deposit",
        "description": "..."
    }
}

  6. Handle successful cash deposit webhooks

    The cashDepositSuccess webhook is triggered after a successful cash top-up operation to wallets belonging to your company. The payload includes detailed information about the user, the mapping of the user in the system, and the specific transaction data including the gateway used, the amount, and branch details.
    {
  "event": "cashDepositSuccess",
  "user": {
    "id": 1,
    "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "region": "TR",
    "locale": "tr",
    "first_name": "Macellan",
    "last_name": "Superapp",
    "full_name": "Macellan SuperApp",
    "email": "altdev@macellan.net",
    "phone": "905231113344",
    "details": {
      "subscribe_sms": false,
      "subscribe_email": false,
      "gender": "male",
      "id_number": "11111111111"
    }
  },
  "waas_user_mapping": {
    "id": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "is_active": true,
    "created_at": "timestamp"
  },
  "data": {
    "id": 1,
    "gateway": "terminal", // Options: terminal, static_qr, box_office, kiosk
    "method": "cash", // Options: cash, credit_card
    "amount": 1,
    "reference_code": 952340,
    "order_id": 95234,
    "created_at": "timestamp",
    "branch": {
      "id": 1,
      "name": "İstanbul",
      "allow_point_usage": true,
      "phone": "+905231113344",
      "code": "12345",
      "description": "İstanbul şubesi"
    },
    "refund_amount": 0,
    "rest_amount": 0,
    "completed_at": "timestamp"
  }
}

  7. Manage customer groups for campaign targeting

    Customer groups are used for targeting and excluding users in campaigns. Groups are created via the Macellan SuperApp panel. Developers can use the associated services to list company groups and add or remove members from these groups.

  8. Handle the depositSuccess webhook event

    The depositSuccess webhook is triggered after a successful deposit into a company's wallets. The payload contains detailed information about the user, the mapping of the user in the system, and the specific transaction data including the gateway used, amount, and payment status.
    {
  "event": "string",
  "user": {
    "id": 1,
    "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "region": "TR",
    "locale": "tr",
    "first_name": "Macellan",
    "last_name": "Superapp",
    "full_name": "Macellan SuperApp",
    "email": "altdev@macellan.net",
    "phone": "905231113344",
    "details": {
      "subscribe_sms": false,
      "subscribe_email": false,
      "gender": "male",
      "id_number": "11111111111"
    }
  },
  "waas_user_mapping": {
    "id": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "is_active": true,
    "created_at": "string"
  },
  "data": {
    "id": 1,
    "gateway": "masterpass",
    "status": "success",
    "reference_code": "95234-111523",
    "amount": 1,
    "final_total": 1,
    "refund_amount": 0,
    "three_d": false,
    "created_at": "string",
    "order_id": "string",
    "deposit_time": "string",
    "installment_count": 2,
    "card_holder": "string",
    "card_bin": "string",
    "pos_bank_no": 12,
    "message": "string"
  }
}

  9. Get user details by mapping ID

    Retrieve detailed information about a user, including their wallet balance and SuperApp profile, using the userMappingId provided during the user creation or linking phase. This ID is essential for Waas operations such as opening Iframes or processing payments.
    GET /waas/integration/users/by-mapping/8b5ac43a-20ce-4987-a739-d8a7ee480eaa

  10. Understand Tag-QR Pricing Types

    Tag-QR allows additional functions to be executed when a user makes a payment via the Macellan SuperApp. There are two pricing models:

    1. Fixed Price (Sabit Fiyat): The amount is predefined in the Macellan SuperApp panel. This is suitable for scenarios like turnstile entries with a constant fee. Only the Ping Callback service integration is required.
    2. Dynamic Price (Dinamik Fiyat): The amount is determined based on the user or other variables and reported to the app. This requires integration with both the Price Service (Fiyat Servisi) and the Ping Callback service.

  11. Handle Point History webhooks

    The pointHistory webhook is triggered whenever a point transaction occurs in wallets belonging to your company. It provides details about the transaction type (usage, load, expire, or revoke), the amount, and the specific point type (e.g., coupon, campaign, gift card). If the point type is campaign, additional campaign details such as the campaign name and code are provided.
    {
  "event": "pointHistory",
  "user": {
    "id": 1,
    "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "region": "TR",
    "locale": "tr",
    "first_name": "Macellan",
    "last_name": "Superapp",
    "full_name": "Macellan SuperApp",
    "email": "altdev@macellan.net",
    "phone": "905231113344",
    "details": {
      "subscribe_sms": false,
      "subscribe_email": false,
      "gender": "male",
      "id_number": "11111111111"
    }
  },
  "waas_user_mapping": {
    "id": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "is_active": true,
    "created_at": "timestamp"
  },
  "data": {
    "id": 1,
    "type": "usage", // Options: usage, load, expire, revoke
    "payment_id": 1,
    "amount": 1,
    "point": {
      "id": 1,
      "type": "campaign", // Options: coupon, user_coupon, campaign, payment_discount, etc.
      "created_at": "timestamp",
      "campaign": {
        "id": 1,
        "name": "Yaz Kampanyası",
        "type": "deposit_gift", // Options: deposit_gift, payment_count_gift, etc.
        "code": "SUMMER2026"
      }
    },
    "created_at": "timestamp"
  }
}

  12. Handle payment completion webhooks

    The paymentComplete webhook is triggered after a successful spending transaction from wallets belonging to your company. The payload includes detailed information about the user, the transaction (including totals, discounts, and reference codes), and any points used during the payment.
    {
  "event": "paymentComplete",
  "user": {
    "id": 1,
    "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "region": "TR",
    "locale": "tr",
    "first_name": "Macellan",
    "last_name": "Superapp",
    "full_name": "Macellan SuperApp",
    "email": "altdev@macellan.net",
    "phone": 905231113344,
    "details": {
      "subscribe_sms": false,
      "subscribe_email": false,
      "gender": "male",
      "id_number": "11111111111"
    }
  },
  "waas_user_mapping": {
    "id": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
    "is_active": true,
    "created_at": "timestamp"
  },
  "data": {
    "id": 1,
    "paid_price": 1,
    "point": 1,
    "final_total": 1,
    "discounted_total_amount": 1,
    "discount_point": 0,
    "refund_amount": 0,
    "reference_code": 123456,
    "order_id": 1405321795,
    "created_at": "timestamp",
    "branch": {
      "id": 1,
      "name": "İstanbul",
      "allow_point_usage": true,
      "phone": "+905231113344",
      "code": "12345",
      "description": "İstanbul şubesi"
    },
    "transaction_code": "V4SBUQG3PMNLCR0",
    "payment_time": "timestamp",
    "point_histories": [
      {
        "id": 1,
        "type": "usage",
        "amount": 1,
        "payment_id": 1,
        "created_at": "timestamp",
        "point": {
          "id": 1,
          "type": "campaign",
          "created_at": "timestamp",
          "campaign": {
            "id": 1,
            "name": "Yaz Kampanyası",
            "type": "deposit_gift",
            "code": "SUMMER2026"
          }
        }
      }
    ]
  }
}