​

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.

​

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

​

Regular A2A Payment

​

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",
    "IBAN":"DE89370400440532013000",
    "storedBIC":"BOFIIE2D",
    "language": "DE"
}

​

Example Response

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

​

2. Retrieve Transaction Status

​

Endpoint

​

Description

​

Request Body Parameters

​

Response Structure

​

Example Request

{
    "referenceId": "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

​

Challenge Deposit (Penny Drop)

​

Introduction

​

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

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