​

Payment Service API - Detailed Documentation

​

API Playground:

​

Key Features

• Redirection Handling: The returned redirect URL should not be embedded in an iframe or an embedded WebView. Instead, a proper browser redirect should be used.
• Customization: The payment page can be customized in terms of UI/UX, so redirection is not an issue.
• Webhooks: Webhooks can be called for by our service if required for more complex operations. You will be able to specify your webhook URL to us at the point when we onboard and set you up for the service. We can customize the flows and reduce the number of calls made to the API by enabling webhooks. Please speak to our specialists when signing up for the service so we can design the flow you require. To properly receive incoming webhooks, your server should provide an endpoint supporting:
  • TLS encryption version 1.2
  • POST requests that are either raw in text/plain if encrypted or application/json if no encryption is activated.
  You can use a service like webhook.site to test receiving webhooks from your developer dashboard. For local testing, you can use a CLI tool such as ngrok to forward the requests to your local development server. When you receive an event, your endpoint should return an HTTP 2xx status code indicating that the event has been successfully received. Webhooks are automatically retried for up to 24 hours if no HTTP 200 status code is returned. The call will also be considered failed if your endpoint doesn’t respond within 10 seconds. When a webhook call fails, we’ll retry the call 6 more times. By default, we wait:
  • 10 seconds between the first and second attempt,
  • 100 seconds between the third and the fourth,
  • 1000 seconds between the fourth and the fifth,
  • 10000 seconds for the last attempt.
• Upcoming Features: Future improvements include a rendered payment button, seamless/modal implementations, and native SDKs.
• Regular Open Banking Payments and Challenge Deposits: The API supports both regular open banking payments and Challenge Deposits, which include additional verification mechanisms such as name matching. These are handled through a dedicated endpoint described separately.

​

Complete Payment Flow Sequence

​

Typical Payment Workflow

​

Endpoints Overview

1. Initiate Payment: Redirects users to the provider’s hosted payment page and initiates a transaction.
2. Retrieve Transaction Status: Retrieves the current status of a payment transaction.
3. Challenge Deposit: Initiates a challenge deposit by sending a small amount to the user’s bank account.

​

Authentication

• Tokens are valid for 60 minutes and must be refreshed after expiration.
• Refer to the Authentication for detailed steps on obtaining a token.
• Include the token in the Authorization header as follows:

​

API Base URL

https://api-umbrella.io/api/services

​

1. Regular A2A Payment

​

1.1 Initiate Payment

​

Endpoint

​

Description

​

Required Headers

​

Request Body Parameters

​

Response Structure

​

Example Request

{
    "amount": "100.50",
    "currency": "EUR",
    "referenceId": "uniqueRefId123",
    "transactionDescription": "Payment for Order #12345",
    "returnUrl": "https://example.com/callback",
    "storedBIC":"BOFIIE2D",
    "language": "DE"
}

​

Example Response

{
    "requestId": "req123456789",
    "redirectUrl": "https://example.com/app/req_123456789"
}

​

1.2 Retrieve Transaction Status

​

Endpoint

​

Description

​

Request Body Parameters

​

Response Structure

​

Example Request

{
    "requestId": "uniqueRefId123"
}

​

Example Response

{
    "status": "PENDING",
    "statusReasonInformation": "User redirected to bank."
}

​

Status Response Fields

​

Supported Languages

• EN
• DE
• SL
• PT
• IT
• FR
• CZ
• PL
• ES
• HU
• NL
• RO

"language": "FR"

​

Common Errors

​

2. Challenge Deposit (Penny Drop)

​

Introduction

​

2.1. Initiate Challenge Deposit

​

Endpoint

​

Description

​

Required Headers

​

Request Body Parameters

​

Response Structure

​

Example Request

{
    "amount": "0.10",
    "currency": "EUR",
    "description": "merchantId19887-65",
    "firstName": "John",
    "lastName": "Doe",
    "piiToggle": 1,
    "nameMatchLogic": "fuzzy"
}

​

Example Response

{
    "requestId": "e5c81c78-272b-4307-9197-3ace19109fd3",
    "description": "merchantId19887-65",
    "status": "OK",
    "globalResult": {
        "overall": "review",
        "totalScore": 100
    },
    "nameMatchScore": 85,
    "iban": "DE44500105175407324931",
    "returnedFirstName": "John",
    "returnedLastName": "Doe"
}

​

Best Practices

​

Security

• Never store bank credentials - Authentication is handled entirely by banks
• Use HTTPS only - All API calls and redirects must use secure connections
• Validate redirect URLs - Ensure returnUrl points to your domain
• Implement CSRF protection - Validate state tokens on return URLs

​

User Experience

• Show clear payment status - Keep customers informed during processing
• Handle timeouts gracefully - Provide clear messaging if authorization expires
• Offer alternative payments - Have backup payment methods available
• Mobile optimization - Ensure redirect flow works on mobile browsers

​

Operations

• Monitor settlement times - Track time from SUCCESS to SETTLEMENT_COMPLETED
• Reconcile daily - Match API statuses with actual bank account credits
• Set up alerts - Monitor for unusual failure rate spikes
• Log everything - Maintain audit trail of all transactions and status changes

​

Performance

• Use webhooks when possible - Reduces latency vs. polling
• Implement intelligent polling - Poll frequently initially, then back off
• Cache status results - Avoid redundant status checks
• Async processing - Don’t block user requests during status checks