Magpie Checkout

How the Magpie hosted checkout session is created, how the user is redirected, and how the result is received.

How Checkout Works

Magpie Checkout is a hosted payment page — Batchmates redirects the user to Magpie's domain where they enter payment details. Batchmates never handles raw card numbers or wallet credentials directly.

Payment methods available via Checkout:

GCash
Maya
Credit / debit card

GCash and Maya payments cannot be saved as reusable payment methods. Each payment requires a fresh authorization. Use Magpie Checkout for these payment types.

Creating a Checkout Session

Endpoint: POST /api/v1/donations

Request Body

Name
campaign_id
Type
integer
Description
Campaign to donate to
Name
amount
Type
number
Description
Base donation amount in PHP (minimum: 1)
Name
payment_gateway
Type
string
Description
Must be "magpie" for the Magpie checkout path
Name
message
Type
string
Description
Optional message (max 500 characters)
Name
is_anonymous
Type
boolean
Description
Default: false

Response

Returns a redirectUrl. The frontend must redirect window.location.href to this URL immediately.

Request

{
  "campaign_id": 1,
  "amount": 1000,
  "payment_gateway": "magpie"
}

Response

{
  "success": true,
  "data": {
    "redirectUrl": "https://checkout.magpie.im/pay/sess_abc123",
    "transaction_id": "sess_abc123",
    "reference_number": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "Payment initiated successfully"
}

Internal Implementation

The checkout session is created inside MagpieTransactionService::initiateCheckoutSession(), which calls MagpieService to hit the Magpie API directly.

// app/Services/MagpieTransactionService.php

public function initiateCheckoutSession(Donation $donation): string
{
    $fees = FeeCalculator::calculate('magpie', $donation->amount);

    $session = $this->magpieService->createCheckoutSession([
        'amount'              => (int) round($fees['total_amount'] * 100), // cents
        'currency'            => 'php',
        'payment_method_types' => ['card', 'gcash', 'maya'],
        'metadata'            => [
            'reference_number' => $donation->reference_number,
            'donation_id'      => $donation->id,
            'campaign_id'      => $donation->campaign_id,
        ],
        'success_url' => route('magpie.success'),
        'cancel_url'  => route('magpie.cancel'),
    ]);

    $donation->update(['transaction_id' => $session['id']]);

    return $session['url'];
}

Success and Cancel Redirects

After the user completes or cancels payment on Magpie's page, Magpie redirects to the Batchmates backend:

Success

GET /api/v1/payments/magpie/success?id={reference_number}

The backend looks up the donation by reference_number, then redirects the browser to:

{FRONTEND_URL}/donations/success?id={reference_number}

Cancel

GET /api/v1/payments/magpie/cancel

The backend redirects to:

{FRONTEND_URL}/donations/cancelled

The success redirect is informational only. The donation is not marked completed here — that happens exclusively via the webhook. Do not rely on the redirect to confirm payment.

Amounts and Fees

Magpie Checkout receives the total_amount (base + fees) in cents. The campaign's raised_amount and available_amount are incremented only by the base amount when the webhook fires.

See Fee Structure for rate details.

Test Mode Caveats

Scenario	Test mode behaviour
Card payments	Fully testable with Magpie test card numbers
GCash	No `action.url` returned — redirect flow cannot be completed
Maya	No `action.url` returned — redirect flow cannot be completed

Use live keys to test the full GCash / Maya redirect flow end-to-end.