Manage accounts and IBANs
The account is the foundation of all features at Swan. It is the base object that every project needs.
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.
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
}
}
}
}
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. They are available only for
Unlimited payment account.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.
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.
You will soon be able to block SEPA Direct Debit at the virtual IBAN level instead of the account level.
Last modified 4mo ago