Transfers

Overview

This section provides a comprehensive understanding of the operations and functionality related to transactions within Crassula.

After following the step-by-step instructions below, you will be able to carry out the following operations:

Set up two-factor authentication (2FA): In this section, we'll guide you through the process of setting up two-factor authentication for the user's account.
Check the client's limits: Understanding how to review a client's withdrawal limits is crucial for effective account management.
Perform transfers between accounts of one client: The ability to transfer funds between accounts owned by the same client is a key feature of any banking application.

2FA

Two-Factor Authentication (2FA) is required for carrying out a payment transaction. Prior to executing a payment, it will be necessary to request the client's list of 2FA methods to ascertain the default 2FA. Typically, this is SMS-based 2FA, but it could also be via a Time-Based One-Time Password (TOTP) application.

2FA methods

Use the following method and parameters to request the list of client's 2FA methods:

Parameter	Value	Description
Base URL	`client.crassula.localhost`	Crassula host URL.
Method	`GET /api/clients/{clientId}/tfa/methods`	Method to send a request to the server.
Header	`Authorization`	JWT or a client API key/master API key

Response example:

BASH

[
{
"id": "54464728-9173-4db7-9602-4a40ff18d859",
"type": 1,
"settings": {
"token": "JKR7YQM9W3EFX1L2"
},
"isDefault": false
},
{
"id": "b11aa9b5-88d7-45fb-9eb2-e073e0b12b57",
"type": 0,
"settings": {
"phoneNumber": "442034614444"
},
"isDefault": true
}
]

Note that Type 0 relates to SMS-based 2FA, while Type 1 is a TOTP 2FA. In the above example, the client has SMS-based Two-Factor Authentication (2FA) set up, and it is utilized as the default method.

Send 2FA SMS

Use the following method and parameters to send verification SMS:

Parameter	Value	Description
Base URL	`client.crassula.localhost`	Crassula host URL.
Method	`POST /api/clients/{clientId}/tfa/confirmation-codes`	Method to send a request to the server.
Header	`Authorization`	JWT or a client API key/master API key

Response example:

BASH

{"recipient": "442034614444"}

Validate 2FA Code

Prior to the utilization of any Two-Factor Authentication (2FA) code, it must be validated. For this purpose, use the method and parameters specified below:

Parameter	Value	Description
Base URL	`client.crassula.localhost`	Crassula host URL.
Method	`POST /api/clients/{clientId}/tfa/validate-code`	Method to send a request to the server.
Header	`Authorization`	JWT or a client API key/master API key

Request body parameters:

The request body contains the following details:

Parameter	Type	Description
`code`	String	2FA code that needs to be validated.
`type`	integer	Type of 2FA: Either 0 or 1.

Request body example:

BASH

{"code":"577104","type":0}

Response body parameters:

Parameter	Type	Description
`valid`	boolean	Indicates whether the code is valid. If the code is invalid, the request will not be successful.

Response body example:

BASH

{"valid": true}

Limits check

Prior to conducting a transaction, it is necessary to ensure that the transaction amount does not exceed the client's set limits.

For this purpose, use the method and parameters specified below:

Parameter	Value	Description
Base URL	`client.crassula.localhost`	Crassula host URL.
Method	`GET /api/clients/{clientId}/is-exceeded-client-limit`	Method to send a request to the server.
Header	`Authorization`	JWT or a client API key/master API key.

Request body parameters:

The request body contains the following details:

Parameter	Description
`account`	The account from which the transfer will be made.
`currency`	Currency of the transfer.
`amount`	Amount of the transfer.
`thresholdType`	Type of the limit being checked: `0` - `TRANSACTION_AMOUNT` `1` - `TRANSACTION_COUNT` `2` - `TRANSFER_COUNT` `3` - `FX_TRANSACTION_AMOUNT`

Response body example:

Example response with no active blocking limit:

BASH

{"exceeded": false,
"thresholdType": null,
"currency": null,
"amount": null,
"transferDirection": null,
"affectsOnlySingleTransaction": false}

Example of response with active blocking limit:

BASH

{"exceeded": true,
"thresholdType": 1,
"currency": null,
"amount": "1.0000000000000000",
"transferDirection": 2,
"affectsOnlySingleTransaction": false}

If "exceeded" is set to "true", the creation of a transaction should not be permitted. Notably, in the current implementation, the request accepts only one type of limit, hence it will be necessary to iterate through three requests for the three transaction limits (0,1,2).

Transfer between own accounts

This subsection covers the process of moving funds within the same client's multiple accounts.

For this purpose, use the method and parameters specified below:

Parameter	Value	Description
Base URL	`client.crassula.localhost`	Crassula host URL.
Method	`POST /api/clients/{clientId}/transfer/self`	Method to send a request to the server.
Header	`Authorization`	JWT or a client API key/master API key.

Request body parameters

The request body contains the following account and other details:

Parameter	Type	Required	Description
`fromAccount`	String	Yes	Outgoing account number.
`toAccount`	String	Yes	Recipient's account number.
`amount`	String	Yes	Transfer amount.
`currency`	String	Yes	Transfer currency.
`details`	String	Yes	Description/purpose of the transfer.
`scheduled`	Boolean	Optional	Defines whether the payment is scheduled to be sent in the future.
`scheduledTime`	String	Optional	An optional parameter that is used when the payment is created as `scheduled` (ISO 8601).

Request body example

BASH

{"fromAccount":"20056940396",
"toAccount":"84979796400",
"amount":"1.00",
"currency":"GBP",
"details":"Transfer between own accounts",
"scheduled":true,
"scheduledTime":"2023-05-16T12:25:00.707Z"}

Response body parameters

The response body contains the following details:

Parameters	Description
`paymentMethod`	A specialized type of payment within a specific destination. For example, for UK Local - FPS, CHAPS.
`currencyType`	Type of transfer currency: `1` - Fiat `2` - Crypto
`referenceTransaction`	Unique ID of the transaction that the created transaction refers to.
`referencedBy`	Unique ID of the transaction that refers to the created transaction. In this case, there will be commission transactions if the commission is applied to the transfer.
`fromAccountIban`	If the transaction uses an IBAN account (as in SEPA payment), it is indicated as the outgoing IBAN.
`beneficiaryAccountIban`	Beneficiary's IBAN.
`providerType`	Type of payment being made, such as SEPA/Local/Swift
`isSelfTransfer`	Indicates whether the payment is an internal transfer between client accounts.
`isDynamicTransfer`	Indicates whether the payment was created through a dynamic payment creation model.
`isScheduled`	Indicates whether the payment is scheduled to be sent in the future.
`id`	Unique transaction ID in the Crassula.
`account`	Full details of the sender's account within Crassula.
`status`	Transaction status in Crassula: DRAFT = `0` PENDING = `1` COMPLETED = `2` DECLINED = `3` REFUNDED = `4`
`state`	Transaction state in Crassula.
`type`	Transaction type in Crassula.
`provider`	The provider that is used to conduct the payment.
`providerId`	Unique ID of the provider that is used during the transfer.
`remitterName`	Sender's name.
`remitterAccountNumber`	Sender's account in Crassula.
`beneficiaryType`	Beneficiary type: `0` - Person `1` - Company
`beneficiaryName`	Beneficiary's name.
`beneficiaryAccountNumber`	Beneficiary's account in Crassula if the payment is internal.
`amount`	Payment amount.
`currency`	Payment currency.
`description`	Payment description specified by the client.
`bankDetails`	Additional banking details that are used when creating the payment.
`createdAt`	Date and time of payment creation.
`executionTime`	Deprecated parameter.
`processingTime`	Date and time of payment processing if the payment is scheduled.
`updatedAt`	The latest date and time at which the payment was updated.
`chargeType`	A tag indicating who will be charged additional fees during payment processing: `SHA` = Shared charges `BEN` = Beneficiary `OUR` = Our customer charged
`urgency`	Deprecated parameter.
`partnerId`	A unique parameter generated by the user, for checking duplicates of outgoing transactions. If the `partnerId` already exists in the system - the transaction will not be created.
`settlementDate`	Date and time of the transaction's transition to the Completed status.

Response body example

BASH

{
    "paymentMethod": null,
    "currencyType": 1,
    "referenceTransaction": null,
    "referencedBy": [],
    "fromAccountIban": "GB07XXXX12345669209566",
    "beneficiaryAccountIban": "NL23ABNA2605052419",
    "providerType": "sepa",
    "isSelfTransfer": false,
    "isDynamicTransfer": false,
    "isScheduled": true,
    "id": "e7e033cf-5966-4669-bb3a-b80926dd2ae8",
    "account": {
        "clientType": 0,
        "clientName": "Name Surname",
        "iban": "GB07XXXX12345669209566",
        "metadata": {
            "status_changed_by": {
                "actor": "Firstname Lastname"
            }
        },
        "providerCurrency": "",
        "external": false,
        "dynamicPayment": false,
        "providerRequisites": {
            "": {
                "bankCode": null,
                "bankAccountNumber": "GB07XXXX12345669209566"
            }
        },
        "number": "12669209566",
        "type": 0,
        "cards": [
            {
                "id": "51b073ca-a88d-4c85-bf51-0c47780942a4",
                "client": {
                    "legalAddress": {
                        "countryCode": "LV",
                        "addressLine1": "Hello World St. 55",
                        "addressLine2": "Hello World St. 56",
                        "city": "Riga",
                        "postalCode": "LV-1001",
                        "state": null
                    },
                    "countryCode": "LV",
                    "permissions": [],
                    "metadata": {
                        "railsbank": {
                            "enduserId": "61810c4a-de59-432f-9a90-f5d760e1fc4e"
                        }
                    },
                    "id": "7ef03fae-2f79-4342-ad9b-c4ba32025062",
                    "publicId": "@nameb9v",
                    "state": 0,
                    "photo": null,
                    "skipTransferPreApproval": false,
                    "updatedAt": "2021-11-02T09:56:07+00:00",
                    "createdAt": "2018-01-29T10:16:39+00:00",
                    "accessRoles": [],
                    "accessRolesMap": [],
                    "verificationLevel": 2,
                    "referralProgram": null,
                    "subscriptionPlan": null,
                    "name": "Name Surname",
                    "transliteratedName": "Name Surname",
                    "firstName": "Name",
                    "lastName": "Surname",
                    "language": "en",
                    "gender": 1,
                    "nationality": "LV",
                    "birthdate": "1990-01-03T00:00:00+00:00",
                    "emails": [
                        {
                            "id": "a0828e09-0e05-45ea-acf7-b92ec66fc9f3",
                            "primary": true,
                            "status": 2,
                            "addedAt": "2017-10-13T13:26:50+00:00",
                            "email": "client@crassula.io"
                        }
                    ],
                    "phones": [
                        {
                            "id": "5e9a69da-8287-4a11-ba43-2417cd229efd",
                            "primary": true,
                            "status": 2,
                            "addedAt": "2017-10-13T12:25:37+00:00",
                            "phone": {
                                "internationalNumber": "37112345678",
                                "number": "12345678",
                                "countryCode": "LV"
                            }
                        }
                    ],
                    "verificationStatus": 4,
                    "passwordUpdatedAt": "2018-01-29T10:16:14+00:00",
                    "defaultCurrency": "EUR",
                    "legalName": "Name Surname",
                    "username": "client@crassula.io",
                    "type": 0
                },
                "provider": "demo",
                "status": 4,
                "type": 0,
                "scheme": 0,
                "mask": "448569******4098",
                "expirationMonth": 5,
                "expirationYear": 2026,
                "cardHolder": "NAME SURNAME",
                "currency": "EUR",
                "settings": {
                    "secure3d": true,
                    "onlinePayments": true,
                    "atmWithdrawal": true,
                    "contactlessPayment": true
                },
                "createdAt": "2023-05-30T23:14:34+00:00",
                "conversionStatus": 0,
                "features": {
                    "show_pin": true,
                    "change_pin": false,
                    "send_pin": true,
                    "switch_3ds": true,
                    "switch_contactless_payment": true,
                    "switch_online_payments": true,
                    "top_up": true,
                    "virtual_to_plastic": true,
                    "show_balance": false,
                    "activation_mode": "cvv"
                }
            }
        ],
        "status": 1,
        "primary": false,
        "name": "Litas sepa multi",
        "provider": {
            "cardIssuer": false,
            "name": "litas_sepa",
            "currency": null,
            "currencies": []
        },
        "providerNumber": "GB07XXXX12345669209566",
        "createdAt": "2023-02-09T16:25:24+00:00",
        "dormant": false,
        "default_fee_activation_date": 0,
        "balances": [],
        "prohibitedOperations": {},
        "discriminator": 0
    },
    "status": 0,
    "state": 22,
    "type": 4,
    "provider": "litas_sepa_mms",
    "providerId": null,
    "remitterName": "Name Surname",
    "remitterAccountNumber": "12669209566",
    "beneficiaryType": 0,
    "beneficiaryName": "Name Surname",
    "beneficiaryAccountNumber": null,
    "amount": -1.0,
    "currency": "EUR",
    "description": "payment",
    "bankDetails": {
        "beneficiaryName": "Name Surname",
        "beneficiaryCode": null,
        "beneficiaryTaxCode": null,
        "beneficiaryAdditionalCode": null,
        "beneficiaryAddress": "address",
        "beneficiaryCity": "city",
        "beneficiaryPostalCode": "1234",
        "beneficiaryState": "state",
        "beneficiaryCountryCode": "FR",
        "remitterAddress": null,
        "remitterCity": null,
        "remitterPostalCode": null,
        "remitterState": null,
        "remitterCountryCode": null,
        "bankName": null,
        "bankCountryCode": null,
        "bankAddress": null,
        "bic": "ABNANL2AXXX",
        "bankAccountNumber": "NL23ABNA2605052419",
        "correspondentBankName": null,
        "correspondentBankAccountNumber": null,
        "correspondentBankCode": null,
        "sortCode": null,
        "bankCode": null
    },
    "createdAt": "2023-06-08T11:16:48+00:00",
    "executionTime": null,
    "processingTime": "2023-06-09T11:17:00+00:00",
    "updatedAt": "2023-06-08T11:16:48+00:00",
    "chargeType": null,
    "urgency": null,
    "partnerId": null,
    "settlementDate": "2023-06-08T00:00:00+00:00"
}

Transfer to another client

This subsection covers the process of moving funds to another client.

For this purpose, use the method and parameters specified below:

Parameter	Value	Description
Base URL	`client.crassula.localhost`	Crassula host URL.
Method	`POST /api/clients/{clientId}/transfer/internal`	Method to send a request to the server.
Header	`Authorization`	JWT or a client API key/master API key.

Request body parameters

The request body contains the following account and other details:

Parameter	Type	Required	Description
`fromAccount`	String	Yes	Outgoing account number.
`toAccount`	String	Yes	Recipient's account number.
`amount`	String	Yes	Transfer amount.
`currency`	String	Yes	Transfer currency.
`details`	String	Yes	Description/purpose of the transfer.
`saveTemplate`	Boolean	Optional	Flag indicating the saving of the payment as a template.
`templateName`	String	Optional	Template name
`scheduled`	Boolean	Optional	Defines whether the payment is scheduled to be sent in the future.
`scheduledTime`	String	Optional	An optional parameter that is used when the payment is created as `scheduled` (ISO 8601).

Request body example

CODE

{"fromAccount":"12669209566",
"toAccount":"13413119267",
"Amount":"12.40",
"currency":"EUR",
"details":"Payment to friend",
"saveTemplate":true,
"templateName":"Internal"
"Scheduled":true,
"scheduledTime":"2023-07-27T11:41:00.089Z"}

Response body example

BASH

{
    "paymentMethod": null,
    "currencyType": 1,
    "referenceTransaction": null,
    "referencedBy": [],
    "fromAccountIban": "GB07XXXX12345669209566",
    "beneficiaryAccountIban": null,
    "providerType": "internal",
    "isSelfTransfer": false,
    "isDynamicTransfer": false,
    "isScheduled": true,
    "id": "1ceeec74-43dd-492b-9ccf-952e442b20d0",
    "account": {
        "clientType": 0,
        "clientName": "Name Surname",
        "iban": "GB07XXXX12345669209566",
        "metadata": {
            "status_changed_by": {
                "actor": "Firstname Lastname"
            }
        },
        "providerCurrency": "",
        "external": false,
        "dynamicPayment": false,
        "providerRequisites": {
            "": {
                "bankCode": null,
                "bankAccountNumber": "GB07XXXX12345669209566"
            }
        },
        "number": "12669209566",
        "type": 0,
        "cards": [],
        "status": 1,
        "primary": true,
        "name": "Litas sepa multi",
        "provider": {
            "cardIssuer": false,
            "name": "litas_sepa",
            "currency": null,
            "currencies": []
        },
        "providerNumber": "GB07XXXX12345669209566",
        "createdAt": "2023-02-09T16:25:24+00:00",
        "dormant": false,
        "default_fee_activation_date": 0,
        "balances": [],
        "prohibitedOperations": {},
        "discriminator": 0
    },
    "status": 0,
    "state": 22,
    "type": 4,
    "provider": "internal",
    "providerId": null,
    "remitterName": "Name Surname",
    "remitterAccountNumber": "12669209566",
    "beneficiaryType": 1,
    "beneficiaryName": "Crypto P.",
    "beneficiaryAccountNumber": "10427771489",
    "amount": -12.4,
    "currency": "EUR",
    "description": "Payment to friend",
    "bankDetails": null,
    "createdAt": "2023-07-27T11:45:19+00:00",
    "executionTime": null,
    "processingTime": "2023-07-27T11:46:00+00:00",
    "updatedAt": "2023-07-27T11:45:19+00:00",
    "chargeType": null,
    "urgency": null,
    "partnerId": null,
    "settlementDate": "2023-07-27T00:00:00+00:00",
}

The response format for all transactions is the same.

See a detailed example in the Response body parameters subsection.