Overview

Pay-by-link is a method that breaks the payment process in two distinct phases:

• the creation of a payment request, operated by the creditor (receiver of funds)
• the acceptance & authorization of the payment, operated by the debtor (the source of funds)

The payment request encapsulates metadata such as: amount, currency, the list of goods to be acquired etc. Once its created, the payment request is wrapped into a transportable object - aka the link- such as a URL or a QR code. The link is sent to a debtor who will only check/approve & authorize the payment.

FinqLink is a platform for developing pay-by-link applications, built on top of the Finqware Payments API. It comes with a simple API for generating payment links and a web application for operating the links. 

Payment providers

• A payment-provider is a partner institution that operates payment services. FinqLink integrates with these providers over APIs such as open-banking payment initiation APIs.
• Each provider has a unique code. Eg: rzb_ro, cec_ro etc.
• A provider may have one or multiple payment-methods offering different capabilities (domestic-only transfers, corporate-only transfers etc)
• we provide an API and a dashboard for quering and visualising all the details regarding providers & methods.

How to test

1. Get a set of API test credentials (contact Finqware)
2. Use the /providers/list endpoint to query for the available/supported payment providers.
3. Create a payment link using the /links/create endpoint. The payment-method will be used to restrict more or less the options shown to the end-user when opening the payment link.
4. Send the payment link to someone in order to operate the payment.

Sandbox testing

• rzb_ro - debtor IBAN: RO03RZBR0000069999999999, creditor IBAN: RO10RZBR0000069999999970, PSU ID: 9999999998
  • Test scenarios: (1) submit the debtor IBAN and/or PSU ID via the API; (2) do not submit them, let the user do the input
• bt_ro - username: testbt, password: testbt, pin: 1234567
• cec_ro - username: testcecapi, password: testcecapi, IBAN: RO42CECEAG0202RON0007466

The Link API is secured by OAuth2 (mandatory for production access) and mTLS (optional).

Mutual TLS (mTLS) and OAuth2 Client Credentials are two distinct security mechanisms that can complement each other to provide robust authentication and secure communication in API integrations.

Note: for testing purposes we also support an internal authentication method that requires client_id/client_secret with each API call. The code examples in this document use this particular method.

Mutual TLS (mTLS)

mTLS is a mechanism for ensuring that both the client and server authenticate each other over a TLS connection. It is an extension of standard TLS (which typically only authenticates the server to the client).

• How mTLS Works:
  1. Client Authentication: In addition to the server presenting its certificate, the client also presents its own certificate to the server.
  2. Certificate Verification: Both parties verify the certificates they receive. This ensures that both the client and server are who they claim to be, providing bidirectional authentication.
  3. Secure Communication: Once both parties are authenticated, a secure encrypted communication channel is established.
• Benefits of mTLS:
  • Strong, cryptographic client authentication.
  • Prevents unauthorized clients from connecting to the server.
  • Ensures data integrity and confidentiality during transmission.

OAuth2 Client Credentials Grant

OAuth2 Client Credentials Grant is a method for obtaining access tokens that can be used to authenticate requests to an API. It is typically used when a client (such as a service or application) needs to access resources or APIs on behalf of itself, not on behalf of a user.

• How OAuth2 Client Credentials Grant Works:
  1. The client (service or application) authenticates with the authorization server using its client ID and secret.
  2. If the credentials are valid, the authorization server issues an access token.
  3. The client uses this access token to authenticate its requests to the resource server (API).
• Benefits of OAuth2 Client Credentials:
  • Provides a mechanism for API clients to obtain access tokens for authenticating requests.
  • Supports fine-grained authorization and scopes to control access to resources.
  • Enables centralized management of client credentials and access policies.

Private Key JWT

Private Key JWT is a method of client authentication where the client creates and signs a JWT using its own private key. This method is described in a combination of RFC 7521 (Assertion Framework) and RFC 7523 (JWT Profile for Client Authentication, and referenced by OpenID Connect and FAPI 2.0 Security Profile.

Although we support the Client Secret (RFC 6749) authentication, we recommend Private Key JWT as it does not involve a process of sharing secrets.

How mTLS and OAuth2 Client Credentials Complement Each Other

When used together, mTLS and OAuth2 Client Credentials Grant provide a powerful combination of strong client authentication and fine-grained authorization. Here’s how they complement each other:

1. Dual Authentication and Authorization:
   • mTLS provides a strong, cryptographic client authentication mechanism, ensuring that only authorized clients (those with valid client certificates) can establish a connection.
   • OAuth2 Client Credentials provides a token-based mechanism for authorizing the client's access to specific APIs or resources. The access token contains information about the client's permissions and access scope.
2. Layered Security:
   • By using both mTLS and OAuth2, you establish multiple layers of security. Even if an access token is somehow obtained by an attacker, mTLS ensures that only clients with a valid certificate can connect. Conversely, even if a client possesses a valid certificate, it still needs a valid access token to access protected resources.
3. Preventing Token Theft and Replay Attacks:
   • With mTLS, the secure communication channel prevents token theft during transmission. Even if a token were somehow intercepted, it would be useless without the client's certificate to establish the connection.
4. Enhanced Security for Sensitive Applications:
   • For highly sensitive applications, combining mTLS with OAuth2 Client Credentials ensures that only authenticated clients (validated by their certificates) and authorized clients (validated by their tokens) can access resources. This is particularly important in zero-trust environments or for internal microservices communication.
5. Compliance and Regulatory Requirements:
   • Some industries require strong client authentication and end-to-end encryption. Combining mTLS with OAuth2 can help meet these regulatory requirements by ensuring secure communication and controlled access.

Summary

By combining mTLS with OAuth2 Client Credentials Grant, you gain the benefits of both strong client authentication and fine-grained access control, enhancing the overall security posture of your application.

mTLS

Setting up mTLS requires two steps. Please contact us for:

• enabling your API Client for mTLS
• sharing your certificate/s in order to be added to our PKI infrastructure

Certificate requirements

• Certificates must use either RSA or ECDSA ciphers.
• For client (leaf) certificates:
  • The Basic Constraints extension must not contain CA=true.
  • The Extended Key Usage extension must contain clientAuth.
  • The Extended Key Usage extension must not contain the codeSigning, timeStamping, or OCSPSigning fields.
  • The certificate must not be expired.
  • The client certificate cannot be a self-signed certificate.
• For root and intermediate certificates:
  • The Basic Constraints extension must contain CA=true.
  • The Key Usage extension must be set to keyCertSign.
  • The Extended Key Usage extension should contain the clientAuth field.
  • The certificate must not be expired.

OAuth2

Setting up OAuth2 requires few steps. Please contact us for:

• enabling your API Client for OAuth2
• sharing the public key which we'll use to verify the signed requests to our Authorization server (example script for generating the public/private key pair)

Getting an access token

Making requests to the Link API in production requires a valid Bearer access token, sent via the standard Authorization header. The process below describes the way to acquire an access token (example script for local tests with curl/Postman)

Your backend is responsible to implement a mechanism for keeping an up-to-date access-token available at all times. There are mature libraries for implementing this process, available in all mainstream programming languages (eg: Java, NodeJS).

Step-1: build a token with a payload such as below and sign it with your private key. The signed token is called a client_assertion in OAuth2 terms.

The example below assumes your client_id is xyz123abc and key id (kid): a1b2c3:

The JSON Header has to specify your key id (kid):

 
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "a1b2c3"
}

The JSON payload:

 
{
  "aud": "https://finqware.okta.com/oauth2/ausfqbxutkZBUKUgQ417/v1/token",
  "iss": "xyz123abc",
  "sub": "xyz123abc",
  "iat": 1741161292,
  "exp": 1741164892,
  "jti": "9CF1E…479C"
}

Step-2: use the client_assertion computed above to make a call to our /token endpoint in order to get an access-token.

 
curl --location --request POST 'https://finqware.okta.com/oauth2/ausfqbxutkZBUKUgQ417/v1/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=xyz123abc' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=pay_by_link' \
    --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
    --data-urlencode 'client_assertion=eyJhbGciOiJSUzI1NiIsIn....le3qGb5mp-yUmPqUwoyZaA9g'

Use the received access-token for making calls to the Link API until its expiration (each access-token is valid for a limited time).