​

Payment Service API - Detailed Documentation

The Payment Service API enables seamless and secure payment processing through open banking. It provides a redirect URL for hosted payment processing, ensuring compliance with banking regulations and providing a streamlined user experience.

​

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

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.

• 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:

Authorization: Bearer YOUR_ACCESS_TOKEN

​

API Base URL

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

​

Regular A2A Payment

​

1. Initiate Payment

​

Endpoint

POST /payments/initiate

​

Description

Initiates a payment by redirecting the user to a hosted payment page.

​

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

POST /payments/status

​

Description

Retrieves the status of a transaction.

​

Request Body Parameters

​

Response Structure

​

Example Request

{
    "referenceId": "uniqueRefId123"
}

​

Example Response

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

​

Status Response Fields

​

Supported Languages

To specify the language for the hosted page, use the language field in the payment initiation request. Supported languages include:

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

Example:

"language": "FR"

​

Common Errors

​

Challenge Deposit (Penny Drop)

​

Introduction

The Challenge Deposit (also known as Penny Drop) is an additional compliance step used for identity verification in regulated markets.

​

1. Initiate Challenge Deposit

​

Endpoint

POST /payments/challenge-deposit

​

Description

Initiates a challenge deposit by sending a small amount to the user’s bank account. It verifies whether the provided name and IBAN match and can optionally return PII details.

​

Required Headers

​

Request Body Parameters

​

Response Structure

​

Example Request

{
    "amount": "0.10",
    "currency": "EUR",
    "referenceId": "uniqueRefId123",
    "firstName": "John",
    "lastName": "Doe",
    "piiToggle": 1,
    "nameMatchLogic": "fuzzy"
}

​

Example Response

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