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.

$3

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

bash

npm install madfoat-sdk

or

bash

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)



$3

tsx

import { PaymentWidget } from "madfoat-sdk";



  currency="AED"

  amount={200}

  payment_reference="by48448t-v585-6689-9459-t4b6d6w4g8ml"

  purpose="AFL"

  email="customer@email.com"

/>





---



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.



$3



Endpoint



GET /v1/lfis





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX





Example Response

json

[

  {

    "id": "233bcd14-4216-4b3c-a362-9e4a9282bba7",

    "organisationName": "Al Tareq Bank",

    "country": "AE"

  }

]





---



$3



Endpoint



POST /v1/payments





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX

Content-Type: application/json





Body

json

{

  "amount": 100,

  "currency": "CZK",

  "payment_reference": "order-12345",

  "payment_purpose": "ACM",

  "email": "customer@example.com"

}





Response

json

{

  "id": "b5d3c444-9e2c-47a4-bef6-8189b44059a0",

  "status": "created",

  "amount": 100,

  "currency": "CZK"

}





---



$3



Endpoint



POST /v1/payments/{payment_id}/charges





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX

Content-Type: application/json





Body

json

{

  "type": "untokenized",

  "source_type": "altareq",

  "lfi_id": "233bcd14-4216-4b3c-a362-9e4a9282bba7"

}





Response

json

{

  "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.



---



$3



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



---



$3



Endpoint



GET /v1/payments/{payment_id}





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX





Query Parameters



consentId: {authorization_code_from_redirect}





Response

json

{

  "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 | !Pay Button |

| Bank Selection | User chooses a bank | !Bank Selection |

| Checkout Screen | Review payment before confirming | !Checkout Screen |

| QR Authorization | Confirm payment via bank | !QR Screen |

| Redirecting | Waiting state after confirmation | !Redirecting |

| Success Screen | Payment successful | !Success Screen |



---



Error Screens



| Error Type | Description | Example |

|-------------|--------------|----------|

| Invalid Params | Missing or invalid props | !Invalid Params |

| Unavailable | API temporarily unavailable | !Unavailable |

| Invalid Merchant | Invalid token or merchant credentials | !Invalid Merchant |

| Unknown Error | Unexpected or unhandled error | !Unknown 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:
support@madfoat.com

Madfoat SDK Documentation

Navigation

Overview

$3

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

Installation

bash

npm install madfoat-sdk

or

bash

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)



$3

tsx

import { PaymentWidget } from "madfoat-sdk";



  currency="AED"

  amount={200}

  payment_reference="by48448t-v585-6689-9459-t4b6d6w4g8ml"

  purpose="AFL"

  email="customer@email.com"

/>





---



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.



$3



Endpoint



GET /v1/lfis





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX





Example Response

json

[

  {

    "id": "233bcd14-4216-4b3c-a362-9e4a9282bba7",

    "organisationName": "Al Tareq Bank",

    "country": "AE"

  }

]





---



$3



Endpoint



POST /v1/payments





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX

Content-Type: application/json





Body

json

{

  "amount": 100,

  "currency": "CZK",

  "payment_reference": "order-12345",

  "payment_purpose": "ACM",

  "email": "customer@example.com"

}





Response

json

{

  "id": "b5d3c444-9e2c-47a4-bef6-8189b44059a0",

  "status": "created",

  "amount": 100,

  "currency": "CZK"

}





---



$3



Endpoint



POST /v1/payments/{payment_id}/charges





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX

Content-Type: application/json





Body

json

{

  "type": "untokenized",

  "source_type": "altareq",

  "lfi_id": "233bcd14-4216-4b3c-a362-9e4a9282bba7"

}





Response

json

{

  "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.



---



$3



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



---



$3



Endpoint



GET /v1/payments/{payment_id}





Headers



X-Application-Key: pk_XXXXXXXXXXXXXXXXXXXXXXXX





Query Parameters



consentId: {authorization_code_from_redirect}





Response

json

{

  "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 | !Pay Button |

| Bank Selection | User chooses a bank | !Bank Selection |

| Checkout Screen | Review payment before confirming | !Checkout Screen |

| QR Authorization | Confirm payment via bank | !QR Screen |

| Redirecting | Waiting state after confirmation | !Redirecting |

| Success Screen | Payment successful | !Success Screen |



---



Error Screens



| Error Type | Description | Example |

|-------------|--------------|----------|

| Invalid Params | Missing or invalid props | !Invalid Params |

| Unavailable | API temporarily unavailable | !Unavailable |

| Invalid Merchant | Invalid token or merchant credentials | !Invalid Merchant |

| Unknown Error | Unexpected or unhandled error | !Unknown 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:
support@madfoat.com