Links

Manage accounts and IBANs

The account is the foundation of all features at Swan. It is the base object that every project needs.

Configure your account

No matter your use case, you will have to handle one or multiple payment accounts. An account is represented by an IBAN and a name. It is where you deposit money and where you receive or initiate payments. To obtain account details you can use the white-label web banking interface or the API.
How a end-user can access the Account details through our #nocode interface
The following query will fetch the IBAN and balance of all the accounts you have access to. If you use this request with the Project Access Token you will get all of your project's accounts, but if you use a User Access Token you will get all the accounts accessible to a specific user.
Request
Response
query MyQuery {
accounts {
edges {
node {
transactions {
edges {
node {
amount {
currency
value
}
statusInfo {
status
}
id
createdAt
type
}
}
}
IBAN
balances {
available {
currency
value
}
}
}
}
}
}
​
{
"data": {
"accounts": {
"edges": [
{
"node": {
"transactions": {
"edges": []
},
"IBAN": "{{YOUR_IBAN}}",
"balances": {
"available": {
"currency": "EUR",
"value": "0.00"
}
}
}
},
{
"node": {
"transactions": {
"edges": [
{
"node": {
"amount": {
"currency": "EUR",
"value": "100.00"
},
"statusInfo": {
"status": "Pending"
},
"id": "{{YOUR_TRANSACTION_ID}}",
"createdAt": "2022-08-08T14:13:05.829Z",
"type": "SepaCreditTransferOut"
}
},
{
"node": {
"amount": {
"currency": "EUR",
"value": "100.00"
},
"statusInfo": {
"status": "Pending"
},
"id": "{{YOUR_TRANSACTION_ID}}",
"createdAt": "2022-08-07T14:13:05.110Z",
"type": "SepaCreditTransferOut"
}
},
{
"node": {
"amount": {
"currency": "EUR",
"value": "100.00"
},
"statusInfo": {
"status": "Pending"
},
"id": "{{YOUR_TRANSACTION_ID}}",
"createdAt": "2022-08-06T14:13:04.993Z",
"type": "SepaCreditTransferOut"
}
},
{
"node": {
"amount": {
"currency": "EUR",
"value": "10000.00"
},
"statusInfo": {
"status": "Booked"
},
"id": "{{YOUR_TRANSACTION_ID}}",
"createdAt": "2022-06-08T09:16:06.458Z",
"type": "SepaCreditTransferIn"
}
}
]
},
"IBAN": "{{YOUR_IBAN}}",
"balances": {
"available": {
"currency": "EUR",
"value": "8832.00"
}
}
}
}
]
}
}
}
To change an account's name use the Edit account button on the white-label web banking interface or the updateAccount mutation. You can also configure whether or not to allow Direct Debit on an account. If you set an account to deny SEPA Direct Debit, every request we received will be rejected. This configuration is only available through the API, using the allowSdd or denySdd mutations.
Replace {{YOUR_ACCOUNT_ID}} with an account id you got in the previous request.
Request to allow SDD
Deny request
mutation MyMutation {
allowSdd(input: { accountId: "{{YOUR_ACCOUNT_ID}}" }) {
... on AllowSddSuccessPayload {
__typename
account {
blockSDD
}
}
}
}
​
mutation MyMutation {
denySdd(input: { accountId: "{{YOUR_ACCOUNT_ID}}" }) {
... on DenySddSuccessPayload {
__typename
account {
blockSDD
}
}
}
}

Manage virtual IBANs

At Swan, when you open up an account for your company, it is automatically assigned a main IBAN. You can then add limitless more IBANs onto that same account; these are your virtual IBANs. Unlike the main IBAN, virtual IBANs only serve to receive SEPA Credit Transfer or SEPA Direct Debit, not initiate them. Like the main IBAN, they are available only for Unlimited payment account.

Create a virtual IBAN

To add an IBAN to your account use the addVirtualIbanEntry mutation. Replace {{YOUR_ACCOUNT_ID}} with your account id.
Request
Response
mutation MyMutation {
addVirtualIbanEntry(
input: { accountId: "{{YOUR_ACCOUNT_ID}}" }
) {
... on AddVirtualIbanEntrySuccessPayload {
__typename
virtualIbanEntry {
IBAN
BIC
id
label
status
}
}
}
}
{
"data": {
"addVirtualIbanEntry": {
"__typename": "AddVirtualIbanEntrySuccessPayload",
"virtualIbanEntry": {
"IBAN": "{{YOUR_IBAN}}",
"BIC": "{{YOUR_BIC}}",
"id": "{{YOUR_VIRTUAL_IBAN_ID}}",
"label": "Virtual",
"status": "Enabled"
}
}
}
}
This will add a virtual IBAN to the account. The end-user can consult the list of virtual IBANs by clicking the Account Details tab. Otherwise, you can query virtualIbanEntries through the account object.
If you want to use this feature for reconciliation purposes you can store the virtual IBAN id and associate it to your client, invoice, renter, etc. Any payment made to this IBAN will be tagged with the virtual IBAN id. Use the event simulator and input the newly created virtual IBAN to generate a SEPA Credit Transfer on your account. Then, use the following query to see the associated virtual IBAN.
Request
Response
query MyQuery {
payments {
edges {
node {
id
transactions {
edges {
node {
... on SEPACreditTransferTransaction {
id
creditor {
... on SEPACreditTransferInCreditor {
virtualIBANEntryId
name
}
}
}
}
}
}
}
}
}
}
{
"data": {
"payments": {
"edges": [
{
"node": {
"id": "{{YOUR_PAYMENT_ID}}",
"transactions": {
"edges": [
{
"node": {
"id": "YOUR_TRANSACTION_ID",
"creditor": {
"virtualIBANEntryId": "{{YOUR_VIRTUAL_IBAN_ID}}",
"name": "Swan Customer Account"
}
}
}
]
}
}
}
]
}
}
}
As you see, the virtual IBAN id belongs to the transaction so you can identify exactly who made the payment.

Revoke a virtual IBAN

To cancel a virtual IBAN, use the cancelVirtualIbanEntry mutation. Replace {{VIRTUAL_IBAN_ID}} with your virtual IBAN id. Any payment made to a canceled virtual IBAN will be rejected.
Request
Response
mutation MyMutation {
cancelVirtualIbanEntry(
input: { virtualIbanEntryId: "{{VIRTUAL_IBAN_ID}}" }
) {
... on CancelVirtualIbanEntrySuccessPayload {
__typename
virtualIbanEntry {
BIC
id
blockSDD
label
status
IBAN
}
}
... on AccountNotFoundRejection {
id
message
}
... on BadAccountStatusRejection {
id
message
}
... on InternalErrorRejection {
__typename
message
}
}
}
{
"data": {
"cancelVirtualIbanEntry": {
"__typename": "CancelVirtualIbanEntrySuccessPayload",
"virtualIbanEntry": {
"BIC": "SWNBFR22",
"id": "{{VIRTUAL_IBAN_ID}}",
"blockSDD": false,
"label": "Virtual",
"status": "Canceled",
"IBAN": "FR7699999002001092505752922"
}
}
}
}
Beware that canceling a virtual IBAN is permanent and you can't reactivate it.

Allow and block direct debit on a virtual IBAN

You will soon be able to block SEPA Direct Debit at the virtual IBAN level instead of the account level.

Next steps

We cannot overemphasize the importance of the account object in your project, therefore it'll be invaluable to you to read the documentation on accounts and IBANs.
You can also move straight on to the next guide: How to make transactions.