Payments

The Payments API allows customers to securely make account-to-account payments in Europe from your app or website in real time.

Finqware Payments API (currently in public beta) enables third parties to set up secure payments on behalf of customers. It provides a unified way of registering new payments on behalf of customers in all integrated banks and works by letting customers connect to their banks and authorize a payment directly from their accounts. Once authorized by the customer, the payment is submitted for processing.

Under PSD2, a 'Payment Initiation Service' is an online service which accesses a user's payment account to initiate a payment with the user's consent and authentication, according to PSD2 regulations

Given the extensive research already done by Swift for ISO20022 standard, the API closely follows the spec as a guideline for architecting the structure of the API. This allows us to integrate different types of payments ranging from Single Domestic Payments to International and Bulk Payments.

Although initially intended to integrate PSD2 Payment Initiation APIs, future extensions will potentially add more capabilities such as working with custom payment APIs (e.g.: private corporate APIs).

Submit Payment Intent step

POST https://api.finqware.com/v1/sessions/:id/steps

- Once an on-boarding session is started, you can submit data using the session_idand thenoncereceived in the previous step. Each session is an iteration of steps.

- Each skill has a different on-boarding process. This example illustrates a payment intent step. At the end of a successful Session, you will receive a SCA link.

Request Body

Name	Type	Description
client_id*	string	A unique id for a tenant app, generated through the developer portal.
nonce*	string	Executing the next step/iteration requires a nonce
skill*	string
step*	string	e.g. "payment_intent"
data*	object	Input data for payment step

200 Successful Strong Customer Authentication (SCA) link

{
  "status": "SESSION_IN_PROGRESS",
  "data": {
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    "method": "GET",
    "url": "https://www.testbank.com/v1/payments/sepa-credit-transfers/authorize?client_id=XXXXXXXXXXX&code_challenge=BYihra....ChCM&code_challenge_method=S256&redirect_uri=https%3A%2F%2Fdev-api.finqware.com%2Fv1%2Fredirects%2Faisp&response_type=code&scope=PIS%3Ac26a97f&state=de53cb2e-...-a092503c1737"
  }
}

400: Bad Request

// check the errors docs page for details
{
  "id": "uuid",
  "type": "invalid_request",
  "http": 400,
  "code": "invalid_client_id",
  "message": "error message"
}

Payment input data object

In particular, we are following the conventions set by the ISO20022 CustomerCreditTransferInitiationV03 message.

• psu_redirect_link: string - An URL the end-user is redirected to after completing the flow, back to the tenant app.

• psu_id: string (optional) - End-user identification information (e.g.: a username used also on the bank's web-banking app). It is required for specific skills.

• group_header: object (optional) - Payment group header; not used in single-payments scenario

  • message_id: string

  • txs_no: number

• payment_info: array - List of elements related to the debit side of the transaction. The information is common to all the credit transfers attached to this Payment Information.

  • payment_info_id: string (optional) - Unique identification of the Payment Information part assigned by the Initiating Party. Used in bulk payments scenarios. Not required for single payments.

  • debtor: object (optional) - Personal information of the debtor

    • name: string - Debtor name

    • address: string (optional) - Debtor address

    • postcode: string (optional) - Debtor postcode

    • country: string (optional) - Debtor ISO3166 Country code

  • debtor_account: object (optional) - Debtor account

    • identification: object - account identification; the only supported option at the moment is IBAN

      • iban: string - IBAN account number;

    • currency: string - 3 Letter ISO Currency Code (ISO 4217)

  • transactions: array - List of Credit Transfer Transaction Information

    • amount: object - amount that needs to be transferred

      • instructed_amount: object - Instructed amount; the only supported option at the moment

        • value: string - amount that needs to be transferred

        • currency: string_ - _3 Letter ISO Currency Code (ISO 4217)

    • creditor: object - Personal information of the creditor

      • name: string - Creditor name

      • address: string (optional) - Creditor address

      • postcode: string (optional) - Creditor postcode

      • country: string (optional) - Creditor ISO3166 Country code

    • creditor_account: object - Creditor account

      • identification: object - account identification; the only supported option at the moment is IBAN

        • iban: string - IBAN account number;

      • currency: string - 3 Letter ISO Currency Code (ISO 4217)

    • payment_identification: object (optional) - Payment identification; required by specific skills.

      • end_to_end_id: string - Unique identification assigned by the payer to identify the transaction. This identification will be returned to the payer and passed on to the beneficiary.

    • remittance_information: object (optional) - Payment details. Credit transfer may contain either free text as unstructured remittance information or structured remittance information, but not both at the same time (with the exception of ERI, which makes it possible to send both at the same time). In currency payments, unstructured information can be used as long as the initiating bank doesn’t change a structured message to an unstructured one.

      • unstructured: string - Payment unstructured details

Example request body

{
    "client_id": "{{client_id}}",
    "nonce": "{{nonce}}",
    "skill": "rzb_ro_pisp1_sbx_#2.0",
    "step": "payment_intent",
    "data": {
        "psu_redirect_link": "http://your_redirect_uri",
        "psu_id": "9999999998",
        "payment_info": [
            {
                "payment_info_id": "123123",
                "debtor_account": {
                    "identification": {
                        "iban": "RO36RZBR5381428631716833"
                    },
                    "currency": "RON"
                },
                "transactions": [
                    {
                        "amount": {
                            "instructed_amount": {
                                "value": "1",
                                "currency": "RON"
                            }
                        },
                        "creditor": {
                            "name": "Madonna",
                            "postcode": "00000",
                            "country": "RO",
                            "town": "Bucuresti",
                            "address": "Bulevardul 1 Mai"
                        },
                        "creditor_account": {
                            "currency": "RON",
                            "identification": {
                                "iban": "RO34RZBR4494386347175899"
                            }
                        },
                        "payment_identification": {
                            "end_to_end_id": "1"
                        },
                        "remittance_information": {
                            "unstructured": "test rzb-ing"
                        }
                    }
                ]
            }
        ]
    }
}

Get payment

POST https://api.finqware.com/v1/payments/get

Retrieve a payment details and/or status updates. Every time this endpoint is called, Finqware makes a back-to-back API call to the bank for updates.

Request Body

Name	Type	Description
client_id*	string	An identifier for your client app.
client_secret*	string	A tenant app secret
credentials_id*	string	A pointer to the payment object
access_token*	string	An auth token for the payment object

200: OK Payment object successfully retrieved.

{
    "id": "e2dbc9cf-d1fd-4d77-9ee7-9864b868dec9",
    "data": {
        "payment_info": [
            {
                "payment_info_id": "123123",
                "debtor_account": {
                    "identification": {
                        "iban": "RO36RZBR5381428631716833"
                    },
                    "currency": "RON"
                },
                "transactions": [
                    {
                        "amount": {
                            "instructed_amount": {
                                "value": "1",
                                "currency": "RON"
                            }
                        },
                        "creditor": {
                            "name": "Madonna",
                            "postcode": "00000",
                            "country": "RO",
                            "town": "Bucuresti",
                            "address": "Bulevardul 1 Mai"
                        },
                        "creditor_account": {
                            "currency": "RON",
                            "identification": {
                                "iban": "RO34RZBR4494386347175899"
                            }
                        },
                        "payment_identification": {
                            "end_to_end_id": "1"
                        },
                        "remittance_information": {
                            "unstructured": "test rzb-ing"
                        }
                    }
                ]
            }
        ]
    },
    "status": "payment_completed"
}

400: Bad Request

// check the errors docs page for details
{
  "id": "uuid",
  "type": "invalid_request",
  "http": 400,
  "code": "invalid_client_id",
  "message": "error message"
}

Payment lifecycle

A payment goes through a number of stages reflected by a changing status.

Status	Description
new_payment_input	The user started a new session and sent the payment details to Finqware
payment_input_submitted	Finqware submitted the payment details to the bank
payment_received	The bank received the payment details and responded with a payment_id
payment_authorized	The user authorized the payment and Finqware received an ACK through a redirect or polling after payment status
payment_in_process	The payment is processed by the bank
payment_completed	The payment is settled in both debtor's and creditor's accounts
payment_failed	Payment cancelled, rejected or failed