Madfoat SDK Documentation

Navigation

• Overview
• Supported Platforms
• Prerequisites
• Get API Keys
• Configure Return URL
• Installation
• Requirements
• Initialize SDK (Client)
• Environment
• Available API Endpoints
• End-to-End Quickstart (Happy Path)
• Error Handling Summary
• Sandbox Test Checklist
• Troubleshooting
• UI Screens
• Error Screens
• Support

Overview

Madfoat SDK is the official React component that provides a complete integration flow for Madfoat payments.
It enables developers to easily accept secure online payments without dealing with low-level API calls or building complex UI screens manually.

Key Features

1. Merchant Authorization – automatic handling of tokens and credentials.
2. Payment Creation – generate payments with all required parameters.
3. Bank Selection – display a list of supported banks for the user to choose from.
4. Checkout Confirmation – review payment details before confirming.
5. QR / Redirect Flow – supports QR code authorization or redirecting to the user’s bank.
6. Redirect Handling – automatically returns users to the merchant app after payment completion.

The SDK includes a modern, pre-built UI for every payment step — no extra coding required.

Supported Platforms

• Web

Prerequisites

• Merchant account onboarded and verified.
• API keys (publishable + secret) issued.
• Return URL configured (must be HTTPS).

Get API Keys

• Find your Publishable (pk_*) and Secret (sk_*) keys in the Madfoat Portal.
• Never include sk_* in client-side apps. Keep it securely.

Configure Return URL

• The SDK automatically handles the return_url during initialization.
• You don’t need to configure it manually in your app or portal.
• After the user completes payment at the bank, the SDK automatically returns them to your app.
• The SDK performs built-in HTTPS validation to ensure a secure redirect.

Installation

npm install madfoat-sdk

or

yarn add madfoat-sdk

Requirements

• React: >=17
• React DOM: >=17
• Node.js: >=16

Peer Dependencies:

• @mui/material ≥ 5.15.0
• @emotion/react ≥ 11.11.0
• @reduxjs/toolkit ≥ 2.9.0

Initialize SDK (Client)

React Component (PaymentWidget)

import { PaymentWidget } from "madfoat-sdk";

<PaymentWidget
  currency="AED"
  amount={200}
  payment_reference="by48448t-v585-6689-9459-t4b6d6w4g8ml"
  purpose="AFL"
  email="[email protected]"
/>

Environment

You can run the SDK from a local environment (e.g. http://localhost:3000) for testing.

Note: Bank redirects may not work on localhost. Use an HTTPS domain for real tests.

Production API Base URL:

https://madfoat-api.k8s.itomy.ch/public

Available API Endpoints

| Category | Method | Endpoint | Description | |-----------|---------|-----------|-------------| | LFI | GET | /v1/lfis | Get list of supported financial institutions (banks). | | Payment | POST | /v1/payments | Create a new payment session. | | Payment | POST | /v1/payments/{payment_id}/charges | Create a payment charge. | | Payment | GET | /v1/payments/{payment_id} | Get payment status. |

End-to-End Quickstart (Happy Path)

This section demonstrates how to perform a full payment flow — from creating a payment session to confirming and checking the final status.

1. Get List of Financial Institutions (Banks)

Endpoint

GET /v1/lfis

Headers

X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX

Example Response

[
  {
    "id": "233bcd14-4216-4b3c-a362-9e4a9282bba7",
    "organisationName": "Al Tareq Bank",
    "country": "AE"
  }
]

2. Create a Payment

Endpoint

POST /v1/payments

Headers

X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Body

{
  "amount": 100,
  "currency": "CZK",
  "payment_reference": "order-12345",
  "payment_purpose": "ACM",
  "email": "[email protected]"
}

Response

{
  "id": "b5d3c444-9e2c-47a4-bef6-8189b44059a0",
  "status": "created",
  "amount": 100,
  "currency": "CZK"
}

3. Create a Payment Charge

Endpoint

POST /v1/payments/{payment_id}/charges

Headers

X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Body

{
  "type": "untokenized",
  "source_type": "altareq",
  "lfi_id": "233bcd14-4216-4b3c-a362-9e4a9282bba7"
}

Response

{
  "charge_id": "ch_4e8a3b3e-441e-4fbb-9a72-678b4fa9b7c1",
  "redirect_url": "https://bank.auth.madfoat.com/authorize?session=abc123",
  "status": "pending"
}

Redirect the user to redirect_url to authorize the payment at their bank.

4. Handle Redirect Back (Return URL)

After successful or failed bank authorization, the user is redirected back to your configured return_url with query parameters:

https://merchant.com/return?code=AUTH_CODE&state=PAYMENT_ID

5. Get Payment Status

Endpoint

GET /v1/payments/{payment_id}

Headers

X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX

Query Parameters

consentId: {authorization_code_from_redirect}

Response

{
  "id": "b5d3c444-9e2c-47a4-bef6-8189b44059a0",
  "status": "success",
  "amount": 100,
  "currency": "CZK",
  "reference": "order-12345"
}

Error Handling Summary

| Stage | Error | Action | |--------|--------|--------| | Before redirect | Invalid props / missing consent | SDK shows validation error | | On return | error param in URL | Show failure screen | | Webhook | Final payment result | Update order UI/status |

Sandbox Test Checklist

Test successful flow
Test user cancel flow
Test failed flow (bank declines)

Troubleshooting

| Issue | Cause | Fix | |-------|--------|-----| | 401 / 403 | Invalid API keys | Check pk_/sk_ values | | No redirect | Invalid Return URL | Must be HTTPS | | No webhook received | Server blocked | Whitelist webhook endpoint |

UI Screens

| Screen | Description | Example | |--------|--------------|----------| | Payment Button | Default entry point | | | Bank Selection | User chooses a bank | | | Checkout Screen | Review payment before confirming | | | QR Authorization | Confirm payment via bank | | | Redirecting | Waiting state after confirmation | | | Success Screen | Payment successful | |

Error Screens

| Error Type | Description | Example | |-------------|--------------|----------| | Invalid Params | Missing or invalid props | | | Unavailable | API temporarily unavailable | | | Invalid Merchant | Invalid token or merchant credentials | | | Unknown Error | Unexpected or unhandled error | |

Tip: Always verify that your Bearer token and X-Application-Key are valid and correctly configured.

Support

For technical questions or integration help, contact our support team:
[email protected]