Example implementation

When building a custom API integration with iwocaPay, your customer will follow a straightforward flow:

• Redirect the customer to iwocaPay.
• Reconcile the order with your back end.

You’ll only need to implement two or three key functions to handle these steps. For reconciliation, you can either:

• Use webhooks to receive updates as they happen (recommended), or:
• Poll for updates on the order (not-recommended).

Below are example integrations in Python, PHP, and TypeScript. They are meant as a guide to help you get started; they are not intended to be used without adaptation and extension in a production environment. In particular, consider:

• Integration with your existing database or back-end systems
• Authentication or user-specific business logic
• Error handling and logging mechanisms
• Deployment in a secure and scalable environment

Note

This code is meant as a guide to help you get started; they are not intended to be used without adaptation and extension in a production environment*.

Customer flow

This is an example customer flow between your checkout and the iwocaPay checkout.

Python

• Directorysrc

  • Directoryconfig

    • env.py
  • Directoryservices

    • iwoca_pay.py
  • Directorywebhooks

    • order_webhook_handler.py
  • Directorymodels

    • iwoca_pay.py
  • Directoryutils

    • http_client.py
  • main.py
• .env

.env

IWOCAPAY_SUPPLIER_ACCESS_TOKEN=access_token
IWOCAPAY_SUPPLIER_UUID=uuid
IWOCAPAY_API_TOKEN=api_token
IWOCAPAY_API_URL=https://stage.iwoca-dev.co.uk/api/lending/edge/

src/config/env.py

from pydantic import BaseSettings

class Settings(BaseSettings):
    IWOCAPAY_API_URL: str
    IWOCAPAY_SUPPLIER_ACCESS_TOKEN: str
    IWOCAPAY_SUPPLIER_UUID: str

    class Config:
        env_file = ".env"

settings = Settings()

if not (settings.IWOCAPAY_API_URL and settings.IWOCAPAY_SUPPLIER_ACCESS_TOKEN and settings.IWOCAPAY_SUPPLIER_UUID):
    raise ValueError("Environment variables are not properly configured.")

src/services/iwoca_pay.py

from src.utils.http_client import http_client
from src.models.iwoca_pay import CreateOrderRequest, CreateOrderResponse, GetOrderStatusResponse

class IwocaPayService:
    def __init__(self, supplier_uuid: str):
        self.supplier_uuid = supplier_uuid

    def create_order(self, request: CreateOrderRequest) -> CreateOrderResponse:
        endpoint = f"/ecommerce/seller/{self.supplier_uuid}/order/"
        response = http_client.post(endpoint, {"data": request.dict()})
        return CreateOrderResponse(**response)

    def get_order_status(self, order_id: str) -> GetOrderStatusResponse:
        endpoint = f"/ecommerce/order/{order_id}/"
        response = http_client.get(endpoint)
        return GetOrderStatusResponse(**response)

src/webhooks/order_webhook_handler.py

from fastapi import APIRouter, Request
from src.models.iwoca_pay import WebhookPayload

router = APIRouter()

@router.post("/webhook")
async def handle_order_webhook(request: Request):
    payload = WebhookPayload(**(await request.json()))

    # Process the webhook data (e.g., update order status in the database)
    print("Received webhook:", payload)

    # Example: Handle specific statuses
    if payload.data["status"] == "CREATED":
        print(f"Order {payload.data['order_id']} has been created.")
    else:
        print(f"Unhandled order status: {payload.data['status']}")

    return {"message": "Webhook processed"}

src/models/iwoca_pay.py

from pydantic import BaseModel, Field
from typing import List, Optional

class CreateOrderRequest(BaseModel):
    amount: float = Field(..., description="The total amount for the order.")
    reference: str = Field(..., description="A unique reference for the order.")
    allowed_payment_terms: Optional[List[str]] = Field(
        None, description="Optional list of allowed payment terms, e.g., ['PAY_LATER']"
    )


class PricingDetails(BaseModel):
    representative_interest: float = Field(..., description="Representative interest rate.")
    promotions: List[dict] = Field(..., description="List of promotions, if any.")


class CreateOrderResponseData(BaseModel):
    id: str = Field(..., description="Unique identifier for the order.")
    amount: float = Field(..., description="The total amount for the order.")
    reference: str = Field(..., description="A unique reference for the order.")
    order_url: str = Field(..., description="The URL for the order checkout.")
    status: str = Field(..., description="The current status of the order.")
    allowed_payment_terms: List[str] = Field(
        ..., description="List of allowed payment terms returned by iwocaPay."
    )


class CreateOrderResponse(BaseModel):
    data: CreateOrderResponseData


class GetOrderStatusResponseData(BaseModel):
    id: str = Field(..., description="Unique identifier for the order.")
    amount: float = Field(..., description="The total amount for the order.")
    reference: str = Field(..., description="A unique reference for the order.")
    redirect_url: str = Field(..., description="URL to redirect the user to after checkout.")
    pricing: PricingDetails = Field(..., description="Details about pricing and promotions.")
    pay_link_id: str = Field(..., description="Unique ID for the payment link.")
    seller_name: str = Field(..., description="Name of the seller.")
    status: str = Field(..., description="The current status of the order.")
    allowed_payment_terms: List[str] = Field(
        ..., description="List of allowed payment terms for the order."
    )


class GetOrderStatusResponse(BaseModel):
    data: GetOrderStatusResponseData


class WebhookPayloadData(BaseModel):
    order_id: int = Field(..., description="Unique identifier for the order.")
    pay_link_id: str = Field(..., description="Unique ID for the payment link.")
    amount: float = Field(..., description="The total amount for the order.")
    reference: str = Field(..., description="A unique reference for the order.")
    status: str = Field(..., description="The current status of the order.")


class WebhookPayload(BaseModel):
    data: WebhookPayloadData

src/utils/http_client.py

import requests
from src.config.env import settings

class HttpClient:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        }

    def post(self, endpoint: str, data: dict) -> dict:
        response = requests.post(f"{self.base_url}{endpoint}", json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get(self, endpoint: str) -> dict:
        response = requests.get(f"{self.base_url}{endpoint}", headers=self.headers)
        response.raise_for_status()
        return response.json()

http_client = HttpClient(settings.IWOCAPAY_API_URL, settings.IWOCAPAY_SUPPLIER_ACCESS_TOKEN)

src/main.py

from fastapi import FastAPI
from src.services.iwoca_pay import IwocaPayService
from src.models.iwoca_pay import CreateOrderRequest
from src.webhooks.order_webhook_handler import router as webhook_router
from src.config.env import settings

app = FastAPI()
iwoca_pay_service = IwocaPayService(supplier_uuid=settings.IWOCAPAY_SUPPLIER_UUID)

# Include webhook routes
app.include_router(webhook_router)

@app.post("/create-order")
async def create_order(request: CreateOrderRequest):
    try:
        response = iwoca_pay_service.create_order(request)
        return response
    except Exception as e:
        return {"error": str(e)}

@app.get("/order-status/{order_id}")
async def get_order_status(order_id: str):
    try:
        response = iwoca_pay_service.get_order_status(order_id)
        return response
    except Exception as e:
        return {"error": str(e)}

Typescript

• Directorysrc

  • Directoryconfig

    • env.ts
  • Directoryservices

    • iwocaPay.ts
  • Directorywebhooks

    • orderWebhookHandler.ts
  • Directorytypes

    • iwocaPay.d.ts
  • Directoryutils

    • httpClient.ts
  • index.ts
• .env

.env

IWOCAPAY_SUPPLIER_ACCESS_TOKEN=access_token
IWOCAPAY_SUPPLIER_UUID=uuid
IWOCAPAY_API_TOKEN=api_token
IWOCAPAY_API_URL=https://stage.iwoca-dev.co.uk/api/lending/edge/

src/config/env.ts

import * as dotenv from "dotenv";

dotenv.config();

export const IWOCAPAY_CONFIG = {
    API_URL: process.env.IWOCAPAY_API_URL!,
    SUPPLIER_ACCESS_TOKEN: process.env.IWOCAPAY_SUPPLIER_ACCESS_TOKEN!,
    SUPPLIER_UUID: process.env.IWOCAPAY_SUPPLIER_UUID!,
};

if (!IWOCAPAY_CONFIG.API_URL || !IWOCAPAY_CONFIG.SUPPLIER_ACCESS_TOKEN || !IWOCAPAY_CONFIG.SUPPLIER_UUID) {
    throw new Error("Environment variables are missing.");
}

src/services/iwocapay.ts

import { httpClient } from "../utils/httpClient.ts";
import { CreateOrderRequest, CreateOrderResponse, GetOrderStatusResponse } from "../types/iwocapay";

export class IwocaPayService {
    private supplierUuid = process.env.IWOCAPAY_SUPPLIER_UUID!;

    async createOrder(request: CreateOrderRequest): Promise<CreateOrderResponse> {
        const response = await httpClient.post<CreateOrderResponse>(
            `/ecommerce/seller/${this.supplierUuid}/order/`,
            { data: request }
        );
        return response.data;
    }

    async getOrderStatus(orderId: string): Promise<GetOrderStatusResponse> {
        const response = await httpClient.get<GetOrderStatusResponse>(`/ecommerce/order/${orderId}/`);
        return response.data;
    }
}

src/types/iwocapay.d.ts

type AllowedPaymentTerms = "PAY_NOW" | "PAY_LATER";

export interface CreateOrderRequest {
    amount: number;
    reference: string;
    allowed_payment_terms?: AllowedPaymentTerms[];
}

export interface CreateOrderResponse {
    data: {
        id: string;
        amount: number;
        reference: string;
        order_url: string;
        status: string;
        allowed_payment_terms: AllowedPaymentTerms[];
    };
}

export interface GetOrderStatusResponse {
    data: {
        id: string;
        amount: number;
        reference: string;
        redirect_url: string;
        pricing: {
            representative_interest: number;
            promotions: any[];
        };
        pay_link_id: string;
        seller_name: string;
        status: string;
        allowed_payment_terms: AllowedPaymentTerms[];
    };
}

export interface WebhookPayload {
    data: {
        order_id: number;
        pay_link_id: string;
        amount: number;
        reference: string;
        status: string;
    };
}

src/utils/httpClient.ts

import axios, { AxiosInstance } from "axios";
import { IWOCAPAY_CONFIG } from "../config/env.ts";

export const httpClient: AxiosInstance = axios.create({
    baseURL: IWOCAPAY_CONFIG.API_URL,
    headers: {
        Authorization: `Bearer ${IWOCAPAY_CONFIG.SUPPLIER_ACCESS_TOKEN}`,
        "Content-Type": "application/json",
    },
});

src/webooks/orderWebhookHandler.ts

import { Request, Response } from "express";
import { WebhookPayload } from "../types/iwocapay";

export const handleOrderWebhook = async (req: Request, res: Response): Promise<void> => {
    const payload: WebhookPayload = req.body;

    // Process the webhook data (e.g., update order status in the database)
    console.log("Received webhook:", payload);

    // Example: Handle specific statuses
    switch (payload.data.status) {
        case "CREATED":
            console.log(`Order ${payload.data.order_id} has been created.`);
            break;
        // Handle other statuses as needed
        default:
            console.log(`Unhandled order status: ${payload.data.status}`);
    }

    res.status(200).send("Webhook processed");
};

src/index.ts

import express from "express";
import bodyParser from "body-parser";
import { IwocaPayService } from "./services/iwocaPay";
import { handleOrderWebhook } from "./webhooks/orderWebhookHandler";

const app = express();
const iwocaPayService = new IwocaPayService();

app.use(bodyParser.json());

// Route for creating an order
app.post("/create-order", async (req, res) => {
    try {
        const { amount, reference, allowed_payment_terms } = req.body;
        const response = await iwocaPayService.createOrder({ amount, reference, allowed_payment_terms });
        res.json(response);
    } catch (error) {
        console.error("Error creating order:", error);
        res.status(500).send("Error creating order");
    }
});

// Route for polling order status
app.get("/order-status/:orderId", async (req, res) => {
    try {
        const { orderId } = req.params;
        const response = await iwocaPayService.getOrderStatus(orderId);
        res.json(response);
    } catch (error) {
        console.error("Error getting order status:", error);
        res.status(500).send("Error getting order status");
    }
});

// Webhook route
app.post("/webhook", handleOrderWebhook);

// Start the server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

PHP

• Directorysrc

  • DirectoryConfig

    • Env.php
  • DirectoryModels

    • CreateOrderRequest.php
    • CreateOrderResponse.php
    • GetOrderStatusResponse.php
    • WebhookPayload.php
  • DirectoryServices

    • IwocaPayService.php
  • DirectoryControllers

    • WebhookController.php
  • DirectoryUtils

    • HttpClient.php
  • Directorypublic

    • index.php
• .env
• composer.json

.env

IWOCAPAY_SUPPLIER_ACCESS_TOKEN=access_token
IWOCAPAY_SUPPLIER_UUID=uuid
IWOCAPAY_API_TOKEN=api_token
IWOCAPAY_API_URL=https://stage.iwoca-dev.co.uk/api/lending/edge/

src/Config/Env.php

<?php

namespace App\Config;

use Dotenv\Dotenv;

class Env
{
    private static ?Env $instance = null;
    private array $env;

    private function __construct()
    {
        $dotenv = Dotenv::createImmutable(__DIR__ . '/../../');
        $dotenv->load();
        $this->env = $_ENV;
    }

    public static function getInstance(): Env
    {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    public function get(string $key, $default = null)
    {
        return $this->env[$key] ?? $default;
    }
}

src/Controllers/WebhookController.php

<?php

namespace App\Controllers;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class WebhookController
{
    public function handle(Request $request): Response
    {
        $data = json_decode($request->getContent(), true);

        if (!$data || !isset($data['data'])) {
            return new Response('Invalid payload', 400);
        }

        // Process webhook payload
        $payload = $data['data'];
        // Example: Update database or trigger business logic
        file_put_contents('php://stdout', json_encode($payload) . "\n");

        return new Response('Webhook processed', 200);
    }
}

src/Models/CreateOrderRequest.php

<?php

namespace App\Models;

class CreateOrderRequest
{
    public float $amount;
    public string $reference;
    public ?array $allowedPaymentTerms;

    public function __construct(float $amount, string $reference, ?array $allowedPaymentTerms = null)
    {
        $this->amount = $amount;
        $this->reference = $reference;
        $this->allowedPaymentTerms = $allowedPaymentTerms;
    }

    public function toArray(): array
    {
        return [
            'amount' => $this->amount,
            'reference' => $this->reference,
            'allowed_payment_terms' => $this->allowedPaymentTerms,
        ];
    }
}

src/Models/CreateOrderResponse.php

<?php

namespace App\Models;

class CreateOrderRequest
{
    public float $amount;
    public string $reference;
    public ?array $allowedPaymentTerms;

    public function __construct(float $amount, string $reference, ?array $allowedPaymentTerms = null)
    {
        $this->amount = $amount;
        $this->reference = $reference;
        $this->allowedPaymentTerms = $allowedPaymentTerms;
    }

    public function toArray(): array
    {
        return [
            'amount' => $this->amount,
            'reference' => $this->reference,
            'allowed_payment_terms' => $this->allowedPaymentTerms,
        ];
    }
}

src/public/index.php

<?php

require __DIR__ . '/../vendor/autoload.php';

use App\Controllers\WebhookController;
use Symfony\Component\HttpFoundation\Request;

$request = Request::createFromGlobals();
$path = $request->getPathInfo();

if ($path === '/webhook' && $request->getMethod() === 'POST') {
    $controller = new WebhookController();
    $response = $controller->handle($request);
    $response->send();
    exit;
}

// Default route for unhandled paths
http_response_code(404);
echo 'Not Found';

src/Services/IwocaPayService.php

<?php

namespace App\Services;

use App\Models\CreateOrderRequest;
use App\Models\CreateOrderResponse;
use App\Utils\HttpClient;

class IwocaPayService
{
    private string $supplierUuid;
    private HttpClient $httpClient;

    public function __construct(string $supplierUuid)
    {
        $this->supplierUuid = $supplierUuid;
        $this->httpClient = new HttpClient();
    }

    public function createOrder(CreateOrderRequest $request): CreateOrderResponse
    {
        $endpoint = "/ecommerce/seller/{$this->supplierUuid}/order/";
        $response = $this->httpClient->post($endpoint, ['data' => $request->toArray()]);
        return new CreateOrderResponse($response['data']);
    }

    public function getOrderStatus(string $orderId): array
    {
        $endpoint = "/ecommerce/order/{$orderId}/";
        return $this->httpClient->get($endpoint);
    }
}

src/Utils/HttpClient.php

<?php

namespace App\Utils;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use App\Config\Env;

class HttpClient
{
    private Client $client;

    public function __construct()
    {
        $baseUrl = Env::getInstance()->get('IWOCAPAY_API_URL');
        $token = Env::getInstance()->get('IWOCAPAY_SUPPLIER_ACCESS_TOKEN');

        $this->client = new Client([
            'base_uri' => $baseUrl,
            'headers' => [
                'Authorization' => "Bearer $token",
                'Content-Type' => 'application/json',
            ],
        ]);
    }

    public function post(string $endpoint, array $data): array
    {
        try {
            $response = $this->client->post($endpoint, ['json' => $data]);
            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            throw new \Exception($e->getMessage());
        }
    }

    public function get(string $endpoint): array
    {
        try {
            $response = $this->client->get($endpoint);
            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            throw new \Exception($e->getMessage());
        }
    }
}

composer.json

{
  "require": {
    "vlucas/phpdotenv": "^5.5",
    "guzzlehttp/guzzle": "^7.0",
    "symfony/http-foundation": "^6.0"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}