Stripe

Category: Payment Hub

Market: UK, EU, US

Business Capabilities

Payment processing, customer management, and card issuing through the Stripe platform. Supports card payments (one-time and recurring), direct debit (BACS and SEPA), refunds, card issuing, and pay-by-link.

Exposed Endpoints

Payment Processing

• Create payment intent: POST /stripe/v1/payments/intent
• Create recurring payment: POST /stripe/v1/payments/recurring
• Refund payment: POST /stripe/v1/payments/refund
• Create unlinked refund: POST /stripe/v1/payments/unlinked-refund
• Attach payment method to customer: POST /stripe/v1/payments/attach

Customer Management

• Create customer: POST /stripe/v1/customers/create
• Get or create customer: POST /stripe/v1/customers/get-or-create
• Search customer by email: GET /stripe/v1/customers/search?email={email}

Direct Debit (BACS and SEPA)

• Setup direct debit: POST /stripe/v1/direct-debit/setup
• Create setup intent: POST /stripe/v1/direct-debit/setup-intent
• Create direct debit payment: POST /stripe/v1/direct-debit/payment
• Get mandate: GET /stripe/v1/direct-debit/mandate/{mandateId}
• Complete direct debit flow: POST /stripe/v1/direct-debit/full-flow
• Save direct debit for future use: POST /stripe/v1/direct-debit/save-flow

Card Issuing

• Create cardholder: POST /stripe/v1/issuing/cardholder
• Create card: POST /stripe/v1/issuing/card
• Activate card: POST /stripe/v1/issuing/activate-card
• Complete card issuing flow: POST /stripe/v1/issuing/full-card-issuing-flow

Pay By Link

• Create payment link: POST /stripe/v1/pay-by-link/create
• Retrieve payment link data: GET /stripe/v1/pay-by-link/retrieve/{id}

Vault Configuration

{
                "auth.disabled.paths": "[\"/stripe/app/browser\",\"/stripe/v1/webhook\"]",
                "ftosapi.url": "https://<your-instance>/ftosapi/automation-processors/actions",
                "stripe.account": "<account-id>",
                "stripe.ftos_endpoint": "/ftos_stripe_webhookapi",
                "stripe.public.key": "<pk-test-or-live>",
                "stripe.secret": "<sk-test-or-live>",
                "stripe.url": "https://api.stripe.com/v1",
                "token.config": "{\"url\":\"https://<your-instance>/auth/realms/<realm>/protocol/openid-connect/token\",\"client_id\":\"<client-id>\",\"client_secret\":\"<client-secret>\",\"grant_type\":\"client_credentials\"}"
        }

Web Integration (iframe)

To integrate the card payment window as an iframe in your web application, use the following pattern:

function initializeStripeIframe(iframeContainerId, data) {

                const baseUrl = data.baseUrl;
                const iframeUrl = data.baseUrl + "/api/stripe/app/browser/index.html";
                let hasSentMessage = false;

                const iframeContainer = document.getElementById(iframeContainerId);
                iframeContainer.innerHTML = "";

                const iframe = document.createElement("iframe");
                iframe.id = iframeContainerId + "_stripe";
                iframe.src = iframeUrl;
                iframe.width = "600";
                iframe.height = "600";
                iframe.sandbox = "allow-scripts allow-same-origin";

                iframeContainer.appendChild(iframe);

                iframe.onload = function () {
                if (!hasSentMessage) {
                var dataToSend = {
                amount: data.amount * 100,       // Amount in smallest currency unit (pence, cents)
                currency: data.currency,          // Currency code (GBP, EUR, USD)
                productName: data.productName,    // Product name
                name: data.name,                  // Customer full name
                email: data.email,                // Customer email address
                token: data.token,                // Data Core auth token (expires in 60 minutes)
                successMessage: "Thank you!",     // Custom success message
                successMessageTitle: "Payment Successful!",
                buttonName: "Make Payment",       // Custom button text (default: "Pay")
                metadata: data.metadata,          // Optional JSON object, returned in webhook
                description: "Payment",           // Optional payment description
                setup_future_usage: "off_session" // "off_session" or "false" (one-time only)
                };

                if (data.isMoto === true) {
                dataToSend.isMoto = true; // MOTO (Mail Order / Telephone Order) transaction
                }

                iframe.contentWindow.postMessage(dataToSend, baseUrl);
                hasSentMessage = true;
                }
                };
        }

Webhook Handling

After a payment is processed, two messages are sent:

1. Synchronous message: sent from the iframe to the parent window via postMessage. Provides immediate feedback about the payment status.
2. Webhook message: sent server-to-server from Stripe to your configured webhook endpoint. This is asynchronous and the most reliable confirmation of payment status.

Use the synchronous message for immediate UI feedback, but rely on the webhook to update your backend and trigger business logic (such as marking an order as paid).

Request Structures and Samples

POST /stripe/v1/pay-by-link/create

Creates a payment link. The response contains the URL to send to the customer.

Sample request:

{
    "name": "customer name",
    "amount": 5000,
    "currency": "gbp",
    "email": "customer@example.com",
    "token": "<data-core-token>",
    "description": "Monthly Subscription",
    "metadata": {},
    "setup_future_usage": "off_session"
}

• amount is in the smallest currency unit (pence, cents, eurocents).
• setup_future_usage accepts "off_session" or "false". If set to "false", no customer is created (one-time payment only). Defaults to "off_session".

POST /stripe/v1/payments/recurring

Creates a recurring payment using a previously stored payment method.

Sample request:

{
    "paymentMethodId": "<payment-method-id>",
    "amount": 300000,
    "currency": "GBP",
    "customerId": "<customer-id>",
    "metadata": {
        "data": {
            "eventId": "...",
            "paymentType": "recurringCardPayment"
        }
    }
}

POST /stripe/v1/payments/refund

Refunds a payment (full or partial) against an existing payment intent.

Sample request:

{
    "paymentIntentId": "<payment-intent-id>",
    "amount": 50000,
    "currency": "GBP",
    "metadata": {
        "data": {
            "eventId": "..."
        }
    }
}

POST /stripe/v1/direct-debit/full-flow

Completes the full direct debit setup and payment in a single call. This example uses BACS.

Sample request:

{
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com",
    "amount": 5000,
    "currency": "GBP",
    "type": "bacs",
    "description": "Subscription Payment",
    "ipAddress": "203.0.113.1",
    "userAgent": "Mozilla/5.0",
    "accountNumber": "00012345",
    "sortCode": "108800",
    "billingName": "John Doe",
    "billingEmail": "john.doe@example.com",
    "addressLine1": "123 Test Street",
    "addressCity": "London",
    "addressPostalCode": "W1A 1AA",
    "setupFutureUsage": "off_session",
    "addressCountry": "GB",
    "metadata": {}
}

POST /stripe/v1/direct-debit/save-flow

Saves a direct debit mandate for future use without creating an immediate payment.

Sample request:

{
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com",
    "description": "Subscription Payment",
    "ipAddress": "203.0.113.1",
    "type": "bacs",
    "userAgent": "Mozilla/5.0",
    "accountNumber": "00012345",
    "sortCode": "108800",
    "billingName": "John Doe",
    "billingEmail": "john.doe@example.com",
    "addressLine1": "123 Test Street",
    "addressCity": "London",
    "addressPostalCode": "W1A 1AA",
    "setupFutureUsage": "off_session",
    "addressCountry": "GB",
    "metadata": {}
}

POST /stripe/v1/payments/unlinked-refund

Creates a refund that is not linked to a specific payment intent.

Sample request:

{
    "paymentMethodId": "<payment-method-id>",
    "customerId": "<customer-id>",
    "amount": 50000,
    "currency": "GBP",
    "description": "Subscription Payment",
    "metadata": {
        "data": {
            "eventId": "..."
        }
    }
}

Error Codes

Errors follow the standard Data Core error response format:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Description of the error"
}