general

Overview

Payment Initiation API aims to make payment providers as simple as a cURL.

Payment Initiation API is available for authorized Payment Initiation Service Providers under PSD2 in the EU and Open Banking in the UK.

Integrations

The Salt Edge platform is incredibly easy to integrate with. We’ve built the Salt Edge Connect interface so your application could start executing payments.

Formats

We use JSON for all the requests and responses, including the errors.

Glossary

Most of the API revolves around several important concepts:

• Customer - an end-user of the client who is consuming Payment Initiation API;
• Provider - a bank or an online payment system;
• Payment - a payment that was made using Payment Initiation API.

Quick Start

Before we proceed, make sure you have a Client account or you should create one on the Sign Up page.

Any request to Account information API is authenticated, so before we are able to fetch any data, we need to create API keys. To do that, visit https://www.saltedge.com/clients/applications first and choose API Keys for the needed application.

Now a new Service API key can be created. You can leave the “Public key” field blank.

Providers that support payments require a provider key in order to be used. To create one, visit Provider Keys.

Note: Only providers that have available payment templates support payments execution.

Each request to API is authenticated with an App-id, and a Secret. Let’s store them as environment variables so that all the later requests are authenticated.

$ export APP_ID=YOUR_APP_ID

$ export SECRET=YOUR_APP_SECRET

Create customer

Before we can create any payments, we need to create a Customer. A Customer in Payment Initiation API is the end-user of your application.

We need to save the Customer id (in this case “222222222222222222”), because we will use it later to create payments.

See customers reference for Customer related API endpoints.

Choose provider

Firstly, we need to choose a provider that supports payments and has client provider keys. We need to execute a request.

The response will be a list of providers that support payments.

Each payment provider can support multiple ways of initiating a payment. Each of this method is called a payment template.

For instance, we can see from the response that provider fake_client_xf supports payment templates SEPA, FPS, and SWIFT.

Choose payment template

Since in previous steps we only added client keys for provider fake_client_xf, we can only execute payments using payment templates supported by this provider - SEPA, FPS, and SWIFT.

For the purposes of this guide, let’s stick with SEPA. We need to save the payment template identifier (in this case SEPA), because we will use it later.

$ export PAYMENT_TEMPLATE=SEPA

To get the payment templates fields, we need to execute the following request.

The response will be a payment template object with payment fields.

From the response, we can see that payment template SEPA requires the following fields (none of them have optional flag set to true, thus all are mandatory):

• end_to_end_id
• customer_last_logged_at
• customer_ip_address
• creditor_name
• creditor_country_code
• currency_code
• amount
• description
• creditor_iban

The data type for each of these fields is represented by the nature field.

Please note, that within the same payment template the set of required and optional payment fields for one provider can vary from the set for other providers.

For example, the below providers have the following required_payment_fields for SEPA template:

1) Erste Bank and Sparkassen (erste_bank_sparkassen_oauth_client_at)

• debtor_iban
• creditor_iban
• amount
• currency_code
• description

2) N26 (token.io) (n26_oauth_client_de)

• debtor_iban
• creditor_iban
• creditor_name
• amount
• currency_code
• description

3) Intesa Sanpaolo (intesa_sanpaolo_oauth_client_it)

• debtor_iban
• creditor_iban
• creditor_name
• amount
• currency_code
• description
• creditor_country_code

Note: According to the SEPA template, the following fields are supposed to be optional debtor_iban, creditor_name and creditor_country_code. However, they became required for those specific implementations from the above.

Thus, we recommend inspecting the provider to see its specific set of required_payment_fields and make sure to pass them during the payment creation.

Initiate payment

To initiate a payment in Salt Edge Connect, we need to execute a request to create a payment.

The response will contain the connect_url. This is the URL we will visit to authorize the user and initiate the payment.

Visit Payment Widget URL

Visit the connect_url from the previous API response. You will be presented with a form for user credentials input. Put “fake” in search and choose a Fake Bank:

Input username and secret as per the on-screen instructions and press Proceed.

After that, you will see the consent window.

After confirming, it will start to initiate the payment.

In case the provider has interactive fields, a form will be presented for filling these fields.

After that, we will have to wait for the payment process to finish.

Try in Postman

Step 1

Install Postman. You can get it on https://www.getpostman.com/apps.

Step 2

Import the postman collection, click the below button to do that.

Step 3

Payment Initiation API requires APP_ID and SECRET headers in order to authenticate its clients. If you don’t have an API key created yet, you can you use our quick start guide to help you create one. Once you have the API key created, you can add its secrets to postman.

Click on the eye on the top right corner and press on “Add” next to “Environments”.

Define variables APP_ID and SECRET with values from the key that you generated on Keys and Secrets page, then add the environment.

Once added, you can select it in the top right corner, and all the requests to Payment Initiation API will be authenticated using your API key.

Try in Swagger

Step 1

Import Swagger JSON, click the button below to do that.

Download Swagger JSON

eIDAS Certificates

Open Banking Gateway supports only soft issued eIDAS certificates and Open Banking UK certificates.

For the purpose of identification, ASPSPs (Account Servicing Payment Service Providers) and TPPs (Third Party Providers) shall rely on using eIDAS (electronic Identification, Authentication and trust Services) Certificates for electronic seal and/or for website authentication. Identifying themselves is mandatory for all TPPs that wish to get access to ASPSP’s sandbox, live API, and/or to non-dedicated channel.

eIDAS Certificates are provided by Qualified Trust Service Providers (QTSPs) who are responsible for assuring the electronic identification of signatories and services by using strong mechanisms for authentication, digital certificates, and electronic signatures.

There are two types of eIDAS Certificates:

• Qualified Website Authentication Certificates (QWAC) - identification at the transport layer. QWAC is similar to SSL/TLS with Extended Validation used in Internet for the same purpose. It is used for website authentication, so that ASPSPs and Third Party Providers (TPPs) can be certain of each other’s identity, securing the transport layer. TPP should present its QWAC client certificate towards an ASPSP. The ASPSP can choose between using the ASPSP QWAC server certificate or just an existing SSL/TLS certificate to receive the TPP’s identification request.

• Qualified Certificate for Electronic Seals (QSEAL) - identification at the application layer. It is used for identity verification, so that transaction information is protected from potential attacks during or after a communication. This means that the person receiving digitally signed data can be sure who signed the data and that it hasn’t been changed.

To create an eIDAS certificate in the Salt Edge system, you should accomplish the following steps:

a. Go to the Client Dashboard.

b. Go to Settings > eIDAS Certificates

c. Choose the certificate type you want to create (QWAC or QSEAL) and press Generate CSR.

d. Send the CSR to the QTSP (you can get test certificate, or buy production certificate)

e. Get a signed certificate from the QTSP

f. Go to Settings > eIDAS Certificates and press edit on previously created record.

g. Insert the received certificate in PEM format into the form and press update.

h. Choose a certificate that you want to use for identification, press edit and mark it as active.

Client Provider Keys

Open Banking Gateway now supports Account Information and Payment Initiation Services channels, which can be used with PSD2 and Open Banking compliant APIs. The connection to such a provider is possible only if you create a Provider Key (set of credentials) for it. In this case, the API keys for Providers are provided and controlled by you. The number of keys is restricted to 1 per provider. After you create the key, the provider will be accessible as an usual provider.

Salt Edge now supports eIDAS Certificates. Learn more.

Integration

To integrate your App’s individual keys with a Financial Provider (ASPSP in PSD2 terms), follow these steps:

• Visit Provider Keys page of your Client Dashboard, select a provider you want add your client keys for, read the instructions and complete the form. You can see all the available providers by going to the New tab on the same page;

• Proceed by visiting the Connect page and search the provider you just created the key for. It will have a small subscript below the provider name stating that this provider is accessed via YOUR_CLIENT_NAME;

• The rest of the process is exactly the same as with usual providers.

Direct API - Salt Edge Connect

In case of using Direct API instead of Salt Edge Connect, it should be ensured that the code handles the new payments’s field nature - dynamic_select, with its options dynamically generated and sent in an Interactive callback.

Testing

For the purpose of testing individual keys Salt Edge has developed the following list of Fake providers:

• fake_client_xf - requires a username and password (embedded);

Sample key:

client_id: "fake_client_id",
client_secret: "fake_client_secret"

• fake_oauth_client_xf - asks for authorization (OAuth redirect);

Sample key:

client_id: "fake_client_id",
client_secret: "fake_client_secret"

• fake_interactive_client_xf - asks to enter a fake captcha code in addition to a username and a password (embedded).

Sample key:

client_id: "fake_client_id",
client_secret: "fake_client_secret"

• fake_interactive_decoupled_client_xf - decoupled interactive flow (e.g. push notification), asks to wait 10 seconds in Connect widget and then click Proceed to continue in addition to a username and a password (embedded).

Sample key:

client_id: "fake_client_id",
client_secret: "fake_client_secret"

Dynamic Registration

Many banks provide the possibility to dynamically onboard in their API. In this context, Salt Edge has a self-service instrument called Dynamic Registration that helps its clients to register quicker with the desired banks’ PSD2 and Open Banking channels.

This type of registration can eliminate manual processes including the need to manually create an account in the bank’s developer portal, fill in of data forms, and lengthy emails exchange with the bank.

To find out if a bank has a dynamic registration on Salt Edge’s side, please follow these steps:

a. Sign in to Client Dashboard.

b. Go to Settings >Dynamic registration.

c. Сlick on New registration and input the desired bank/group name, then complete the form.

e. As a result, you will get a message with the status of Dynamic Registration.

f. On your Provider Keys page all the providers related to that Dynamic Registration will now appear. You will also notice that they’re categorized as Dynamic registration type.

Types of Dynamic registration

Salt Edge supports the following types of dynamic registration:

Dynamic registration that executes an API request

This is the base dynamic registration aimed at consuming the registration API implemented by the bank. Currently, this dynamic registration is separated into three subtypes:

• A registration endpoint that will create a new client and/or application on the bank’s side;
• An API endpoint that will update the eIDAS certificates associated with an already registered TPP;
• A validation endpoint that only verifies the validity of the eIDAS certificate.

Dynamic registration that doesn’t execute an API request

This type of dynamic registration does not contain any request to the bank, and its purpose is solely to help Salt Edge’s clients to add multiple client provider keys at once without the need to do it manually.

For example, the dynamic registration CBI Globe will add the client provider keys to 300+ providers, which means Salt Edge’s clients won’t need to do it manually for every provider separately.

Instruction

Every dynamic registration template contains an instruction which provides more details about its purpose and what additional steps must be done.

Dynamic registration result

Any dynamic registration attempt will result in one of the following:

Successful registration

A pop-up window with a confirmation message will be displayed. The client should save the displayed result for future reference and use.

The Client Provider Keys will be automatically added to all the associated providers.

Note: Sometimes the clients are required to perform additional steps after a successful registration. All additional information will be displayed in the pop-up window or in the initial instruction.

Failed registration

A pop-up window with the error’s details will be displayed.

If the error was raised by the bank and Salt Edge didn’t handle this error yet, the pop-up window will contain also the Date of the request and the response Salt Edge received from the bank.

Depending on the nature of the error, Salt Edge’s clients will have to:

• Adjust some of the information they input in the required dynamic registration fields;
• Address the issue with their Salt Edge representative;
• Contact the bank directly to report the problem.

Most common dynamic registration errors

Validation of the certificates failed

Possible error messages:

• Validation of QWAC failed
• Validation of QSealC failed
• Check on EBA register failed

The bank didn’t accept the TPP’s eIDAS certificates or EBA register check has failed. Hence, the TPP should contact and ask the bank to add their certificate in the bank’s trust store. If this is not the case, the bank will investigate additionally why the certificates were not accepted.

TPP already registered

Possible error messages:

• TPP Application was already registered
• Organization already exists

The TPP is already registered in the bank’s system, either using manual process or via Salt Edge. Hence, the TPP should contact the bank and clarify how to solve the encountered problem. The solution can differ depending on the bank.

Before going LIVE

In order to upgrade your Client account status to LIVE mode, the following steps should be followed:

• Be sure to provide the signature in accordance with the instructions.
• Your application should handle correctly a few fake banks (fake_oauth_client_xf, fake_client_xf are mandatory).
• The Two-factor authentication must be enabled for your account and all your teammates;
• Be sure to indicate Incident reporting Email in the dashboard settings on the Company page.
• Perform at least one successful payment initiation test with each provider from your key market.

After your Account Manager at Salt Edge has reviewed the app’s integration with Payment Initiation API and made sure that payment initiation tests were successfully performed, the account’s status will be upgraded to live.

Salt Edge Connect

The most simple and easy way to execute payments in Payment Initiation API is to use Salt Edge Connect.

Salt Edge Connect is a web page that handles all the user interaction during a payment initiation process:

• user credentials input
• interactive confirmation
• progress reporting
• error reporting

After your application has received an URL for executing a payment using Salt Edge Connect, you can redirect your end-user to it. There, they will see a screen that lets them pick a provider to execute a payment.

Your user will also be asked to input credentials and, if needed, any of the interactive credentials. After the process is done, the user will be redirected back to your application URL, or to the URL specified as return_to argument to create payment endpoint.

You can easily test Connect from your Dashboard page by pressing New Payment button or by using the create payment route.

Embed connect in your app

At the moment, the only way to embed Salt Edge Connect in your application is to open it in a pop-up. When opening it in a pop-up using window.open, it will post notifications during the payment process. To enable these notifications when you request an URL for executing payments, you can pass an optional argument javascript_callback_type with the value post_message.

This tells Salt Edge Connect to use postMessage for sending messages to a parent window. You can then subscribe to those messages by calling window.addEventListener("message", callback) in the parent window.

Callbacks

The most important parts of Payment Initiation API (e.g. Payment initiation) are asynchronous.

Every Web application has to provide a set of valid URLs which will be used to notify about the payment progress. Other applications can poll Payment Initiation API in order to retrieve the current payment status.

There are several common points about the request we send to the callback URLs provided by the client:

• The Content-Type header is application/json;
• There is a Signature header that identifies the request was signed by Payment Initiation API;
• The request method is always POST;
• The JSON object sent will always have a data field;
• The meta field will display the version of the callbacks API.

You can set the callback URLs for your application by accessing your Payment Initiation tab on the callbacks page.

Due to security reasons, the callbacks can be sent to ports 80/HTTP (in test and pending modes) and 443/HTTPS (in test, pending and live modes) only!
Also, the callbacks do not follow redirects.

Signature

In order for the client to identify that the request is coming from Payment Initiation API, there is a Signature header in the request.

Signature - base64 encoded SHA256 signature of the string represented in the form callback_url|post_body - 2 parameters concatenated with a vertical bar |, signed with a Payment Initiation API’s private key. You can find the version of the signature key used to sign the callback in the Signature-key-version header. The current version is 4.0 which corresponds to the following public key:

  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzi1XL1b0XwUYVHj7/AR6
  Hr0YN34wH/bDOIub0nwt0s/s3tD+DPxNB85xpMEZrLikPW5PAKkQ/oC3OyPYxKOb
  8TNhzGmQhEfyCkbdRwxNZqRMRwuOc+N4sdBtQKPN8+XF3RIcRZAk25JGROtb1M2o
  d/Nb9QqdQwMjdk6W+Vdq5Sj25Tj2efJc8zmBJkNXR4WtW45p4XSdjSEjuVCSZjOy
  +N8/Od8MGixC99jYbiKm3RrVDJCgDi4YYnNRI0QgxZRpJKbQX/WeZiYOrbctG3m8
  l1/Hpkv3w1QHz/YFIshCOKwUL+xg1hLMaW4IH7XFHenE+JlUKdCqhcWyi7oIDkyr
  7wIDAQAB
  -----END PUBLIC KEY-----

An example of the string that is to be used to generate the signature looks as follows:

https://www.client.com/api/payments/callbacks/success|{"data":{"payment_id":"131313131313131313","customer_id":"222222222222222222","custom_fields":{},"status": "processing"},"meta":{"version":"1","time":"2021-01-03T13:00:28Z"}}

The pseudocode that we use to generate the signature looks like this:

base64(sha256_signature(private_key, "callback_url|post_body"))

Success

We send a callback to your application’s success URL whenever an operation has caused a change in the data we store for a particular payment.

For instance, after you’ve redirected your users to the Connect page and they have selected a provider, gave consent and pressed Proceed, we’ll send you a success callback. This callback will contain the customer identifier, the id of the newly created payment and its status. Afterwards, your application will be able to use the show payment route and query the information about this payment.

Whenever there is more information about the payment, we will send another success callback.

A success callback marks a change in the data and you can generally expect from one to three success callbacks with the same payload within several minutes. We recommend that your application fetch the full payment data at each callback, as some information might change during the fetching process.

For instance, when your user has initiated a payment using Salt Edge Connect, we will send the following success callback:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2023-09-13T08:36:17.098Z"
  }
}

You can now use the show payment route and obtain the provider and some other attributes of the new payment.

Failure

Sometimes, a payment might fail to go through. This might happen because for some reason it could not be performed.
In this case, you will receive a fail callback, containing a JSON similar to the following:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "status": "rejected",
    "error_class": "PaymentFailed",
    "error_message": "Payment cancelled"
  },
  "meta": {
    "version": "1",
    "time": "2023-09-13T08:36:17.116Z"
  }
}

After you get this callback, you need to request the payment to check for its updates. Please note that even if there’s an error, the payment_id will still be stored.

Notify

After a new payment was created in the payment initialization process, Salt Edge can inform you about the payment’s progress via a notify callback.

Your app can expect the notify callback several times, but you can use this information to inform your end-user about the payment’s progress.

The possible stages sent in a notify callback are described here.

Here’s an example callback sent to the /notify route of your app:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "submission",
    "stage_id": "242424242424242424",
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2023-09-12T08:36:17Z"
  }
}

For some of the payments you might not receive all the stages.

Interactive

Some of the providers require an additional step in the payment initialization process, asking users to input an SMS, Token, solve a CAPTCHA, etc.

Whenever we encounter that the payment initialization process requires an interactive step, we will send the interactive callback to the interactive route set in your app’s profile. Your app should prompt the users for the interactive credentials and send them to the confirm route.

We also send a snippet of HTML so that it would be easier for your app to display the CAPTCHA or image to the user. If the provider requires filling a CAPTCHA, the img tag in the HTML will contain the image URL.

During this process, the payment’s stage will be set to interactive.

The interactive callback should contain the values of the interactive_credentials field from the corresponding provider.

Here’s an example callback sent to your app’s /confirm route:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "status": "processing",
    "html": "<div id='interactive'><img src='https://docs.saltedge.com/images/saltedge_captcha.png' width='10' height='10' alt='some description' title='some description'></div>",
    "stage": "interactive",
    "stage_id": "242424242424242424",
    "session_expires_at": "2023-09-12T09:36:17Z",
    "interactive_fields_names": ["image"],
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2023-09-12T08:36:17Z"
  }
}

Interactive Redirect

Some OAuth providers require 2 redirects for payment authorization. In these cases, for the 2nd redirect Salt Edge will send an interactive callback with redirect_url field:

{
  "data": {
    "payment_id": "131313131313131313",
    "customer_id": "222222222222222222",
    "status": "processing",
    "html": "",
    "redirect_url": "https://bank.com/authorize"
    "stage": "interactive",
    "stage_id": "242424242424242424",
    "session_expires_at": "2023-09-12T09:36:17Z",
    "interactive_fields_names": [],
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2023-09-12T08:36:17Z"
  }
}

In these cases, your application should redirect the user to redirect_url field value of the interactive callback payload. Once the end-users are authorized on the provider’s side, they will be redirected to the return_to URL indicated in the initiate payment request, with a bunch of parameters appended to it by the provider that are needed for authorizing the payment. Those parameters need to be sent to the payments confirm route as query_string field.

Errors

The Payment Initiation API can return multiple errors for any operation, each having its meaning and usage.

Attributes

Payment status

• failed - the payment failed due to an error on the bank’s side.
• unknown - the payment didn’t reach the end status on the bank’s side. The status can be unknown until we get an updated status from the bank (either rejected or accepted).
• rejected - the payment was rejected either by the user or by the bank. It can be rejected explicitly or due to different errors on the bank’s side.
• no payment object created - an error happened before the payment was created.

Bank integration layer

• Errors could take place either between Salt Edge and the bank, or on the bank’s end.
• Some of the errors are displayed to the end-users, while others are hidden.
• There are multiple reasons which cause the errors, for example, bank issues, incorrect user actions, invalid PSD2 access, etc.
• ProviderError and ExecutionTimeout errors should be reported to Salt Edge.
• The rest of the errors from the below table are caused by incorrect actions of end-users.

Payments API Reference

• Errors can occur if the client configures API requests incorrectly.
• These errors are not displayed to end-users.
  

Client Configuration

• Errors can happen if the client’s account isn’t configured properly.
• They will not affect payments as none of these errors will allow initiating a payment.
• These errors should be reported to Salt Edge.

FAQ

Can you set up scheduled payments for varied or fixed amounts?

Scheduled Payments support only fixed amounts under existing Payment Initiation API.

Do I need a PIS licence to initiate payments?

Yes, Salt Edge Clients should be authorized PISP in the UK and/or EU with a valid set of eIDAS (Open Banking UK) certificates.

Can I issue cross border payments?

Yes, depending on the ASPSP (Provider) API payment product availability.

Can a merchant be added as a trusted beneficiary?

Beneficiary APIs are currently available as premium APIs, with only a small number of banks supporting such functionality. Salt Edge plans to add support for Beneficiary APIs in the future.

Which banks can I use to make payments from a Business Account?

Providers with an supported_account_types array that includes business accounts.

How long will payments take to settle?

This strongly depends on the Payment Product, payment scheme and the ASPSP’s (Provider) internal process.

How can I reconcile a payment?

Using end_to_end_id and/or reference that you can receive via AISP APIs on the creditor account.

Do I need to onboard with each bank?

It depends on the ASPSP’s (provider’s) API. If it allows Dynamic Registration and onboarding using eIDAS or Open Banking UK certificates, Salt Edge provides a Dynamic Registration option in the Client Dashboard.

Otherwise, you will need to register and onboard with each ASPSP (Provider) manually and upload the required information to the Provider keys section of the Client Dashboard. For more information, please refer to the Client Provider Keys section.

How do I register several applications?

By Signing Up multiple Client Accounts. We are looking to provide Application Management from the Client Dashboard during 2021.

How and when do I get a payment_id?

When creating a Payment Order, you need to populate Payment attributes which include a mandatory field as the end_to_end_id, which will be sent to the ASPSP Payment Initiation endpoints. Once the Payment Order is accepted by the Debtor ASPSP for execution, the same end_to_end_id will be sent to the Creditor ASPSP as a part of remittance information. Each Payment Order is also associated with a Salt Edge payment_id to allow listing payments with all associated payment attributes.

Do I have to send the provider_code for each payment request?

Payment Initiation API is not linked to existing connected banks of the Customer. You need to provide the provider_code if you are trying to execute a payment from a Bank or connection known by the Customer.

What is the difference between optional and required payment fields?

Required fields are mandatory for a payment to be initiated, while optional fields are supported by the provider for additional information. If optional fields are passed, however, they not even present in the optional_payment_fields, they will be logged on our side, but not used for payment initiation.

Why the very same payment template can have different sets of required and optional payment fields for different providers?

Depending on the standard the bank implemented PISP and functionality it decided to expose, the set of required and optional fields for a payment template can vary for different providers. Some optional fields from a template may become required for a specific provider.

What are the recommendations for the description field?

Most ASPSPs have certain limitations in place when it comes to the formatting of the unstructured payment remittance information (description). Using alphanumeric characters along with ., ,, -, /, ?, (, ), +, ' and spaces as well as keeping the length of the description under 1000 characters should be a safe approach for most ASPSPs (RegExp: /[A-Za-z0-9.-,()+'? ]{2,1000}/). ASPSPs may extend these constraints depending on their core banking system, payment schema and other relevant factors.

How cross-border payments work in Fiducia hub?

At this moment there is no possibility to do a full check prior to the payment initiation whether the payment goes under SEPA or cross-border payment schemes with Fiducia hub providers.

This is how SEPA and cross-border payments are handled on Fiducia’s end:

In principle, a distinction must be made between a normal SEPA credit transfer and a foreign credit transfer. This distinction is to be made on the part of the third party provider and not on the part of the third party provider interface.

Example: A payment is to be made to a beneficiary in France, but in US dollars or with a special fee regulation/instruction, or only one account number is known for the beneficiary, etc.

On Salt Edge’s end SEPA and cross-border payments are handled under SEPA and SWIFT payment templates correspondingly.

Considering there are payment conditions and criteria which can’t be controlled or influenced by TPPs, if the criteria are not met according to the response received from the bank during payment initiation, Salt Edge will return the following errors:

1) PaymentFailed with the message Cross Border Payment is not supported. Please retry using SEPA payment scheme.
2) PaymentFailed with the message Please retry using the cross-border (SWIFT) payment scheme.

api

Pay with Connect

The easiest way to initiate payments using Payment Initiation API is to use Salt Edge Connect, which handles all the authentication interaction with the user. After the request is executed, you will receive a connect_url field, which the user should be redirected to in order to process with the payment flow.

Please see the sequence diagram for details on how to handle payments via Connect.

Parameters

Possible Errors

Pay with Direct API

If you wish to handle the credentials, consent and authorization for payments yourself, you can create payments directly via the API.

Create

Your app will have to pass the user’s values of provider’s fields within the payload in the credentials object. Please note that you still have to use redirects (see OAuth in all cases when the provider mode is oauth).

The credentials object should be modeled after the provider’s fields. For instance, if the provider’s required fields contain a field with the value of name equal to username, the credential object should contain a username attribute with the value being the actual username.

For example, here’s a provider:

{
  "data": {
    "code": "bigbank_us",
    "required_fields": [
      {
        "english_name": "Pass Code",
        "localized_name": "Pass Code",
        "name": "code",
        "nature": "text",
        "position": 1
      }
    ]
  }
}

The user should be prompted to input Pass Code. If they input Pass Code (in this case, “hunter2”), your app should send the following data in the credentials object:

{
  "code": "hunter2"
}

Here’s another example that includes a select:

{
  "data": {
    "code": "anotherbank_us",
    "required_fields": [
      {
        "english_name": "Password",
        "localized_name": "Password",
        "name": "password",
        "nature": "password",
        "position": 1
      },
      {
        "nature":         "select",
        "name":           "image",
        "english_name":   "Image",
        "localized_name": "Imagine",
        "position":       2,
        "optional":       false,
        "field_options": [
          {
            "name":           "1",
            "english_name":   "Home",
            "localized_name": "Casa",
            "option_value":   "home",
            "selected":       false
          },
          {
            "name":           "2",
            "english_name":   "Car",
            "localized_name": "Automobil",
            "option_value":   "car",
            "selected":       false
          }
        ]
      }
    ]
  }
}

In this case, your app should prompt the user to input Password and offer selecting the options of “Casa” and “Automobil” (the localized_name or english_name values, depending on your service). The credentials should contain the name of the select field (in this case image) as the key and the user’s selected option_value as its value. Let’s say the user has input hunter2 as the password and has chosen “Automobil” from the select.

The credentials object should look like this:

{
  "password": "hunter2",
  "image": "car"
}

Please see the sequence diagram for details on how to handle embedded payments correctly.

Payments workflow does not currently support encrypted credentials.

Parameters

Possible Errors

OAuth

Since initiating payments with OAuth providers implies a redirect, the flow for these providers is similar to Pay with Connect. The response will contain a redirect_url and your app has to redirect the user to that URL.

The redirect_url points to a page where the user can provide PISP access to make payments, making it available for your app. After the users have approved PISP in the OAuth provider’s interface, they will be redirected to the return_to page.

• Note that return_to is optional for clients only if a shared (owned by Salt Edge) provider key is used (defaults to the client’s home_url);
• If clients use their own provider keys, return_to is mandatory and should be a valid URL that was registered within the chosen provider.

Please see the sequence diagram for details on how to handle OAuth payments directly.

Parameters

Possible Errors

Authorize

Used to authorize a payment for an OAuth provider when using client owned provider keys. In this flow, once the end-users are authorized on the provider’s side, they are redirected to the return_to URL indicated in the previous request, with a bunch of parameters appended to it by the provider that are needed for authorizing the payment.

Examples:

<return_to url>?code=bc4521d3&state=Pd8b4d0eb
<return_to url>#code=bc4521d3&state=Pd8b4d0eb

For both cases, the query_string that is needed to authorize the payment is code=bc4521d3&state=Pd8b4d0eb.

Please note that in some PSD2 specifications the end-user will be redirected to return_to with no additional parameters due to the lack of need to make additional Authorization requests. For such cases, an empty query_string value is acceptable, for example:

{
  "data": {
    "payment_id": "131313131313131313",
    "query_string": ""
  }
}

If the provider returned an error on return_to redirect, thar error should be sent the same way as a successful redirect would be, namely, with parameters in the query_string field:

{
  "data": {
    "payment_id": "131313131313131313",
    "query_string": "error=InternalServerError&message=PSU+SCA+error&state=Pd8b4d0eb"
  }
}

Parameters

Possible Errors