# Payments 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_id`and the`nonce`received 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 | {% tabs %} {% tab title="200 Successful Strong Customer Authentication (SCA) link" %} ```javascript { "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" } } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript // check the errors docs page for details { "id": "uuid", "type": "invalid_request", "http": 400, "code": "invalid_client_id", "message": "error message" } ``` {% endtab %} {% endtabs %} #### 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 ```javascript { "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 | {% tabs %} {% tab title="200: OK Payment object successfully retrieved." %} ```javascript { "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" } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript // check the errors docs page for details { "id": "uuid", "type": "invalid_request", "http": 400, "code": "invalid_client_id", "message": "error message" } ``` {% endtab %} {% endtabs %} #### 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 |