IBAN Opening
This guide provides a structured process for opening IBAN account.
Important
Before submitting an IBAN issuance request, ensure you have completed identity verification and subscribed to a plan that supports IBAN creation.
1. Create an IBAN issuance request
Endpoint:
If successful, it retrieves the request identifier, status, and the identifier of the invoice to be paid.
Body Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
currency | string | ✅ | Currency of the IBAN account — only EUR is available. |
Response Example:
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"invoiceId": "string",
"status": "INIT"
}
2. Get Invoice by ID
Endpoint:
Retrieves an invoice by its ID if it is available for the user.
Path Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id | string | ✅ | the invoice ID. |
Response Example:
{
"status" : "INIT",
"payments" : [ ],
"lastModifiedDate" : "2025-04-22T10:16:56.773584Z",
"recurrentInvoiceId" : "c2cc3212-7bd5-44f7-a6b0-50ba2beedf11",
"externalClientId" : "8a7b9019-bec5-4580-9b34-31a0b8fb613f",
"id" : "8ff3635a-0f80-40a1-8eb3-555802c0635d",
"amount" : 3,
"currency" : "usd",
"type" : "ORIGINAL",
"alignable" : true
}
Optional. Apply Discount to Invoice
Endpoint:
PUT /acquiring/invoice/{invoiceId}/discount
Enables clients to apply promotional discounts before finalizing the payment.
Path Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceId | string | ✅ | the invoice ID. |
Query Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
discountCode | string | ✅ | the discount code to be applied to the invoice, which may provide a percentage or fixed discount. |
Response Example:
{
"status" : "INIT",
"payments" : [ ],
"discountCode" : "WELCOME100",
"amountBeforeDiscount" : 102,
"lastModifiedDate" : "2025-04-22T10:22:47.441401859Z",
"recurrentInvoiceId" : "034cd818-18ca-4896-bfe2-cc7c445320cb",
"externalClientId" : "8a7b9019-bec5-4580-9b34-31a0b8fb613f",
"id" : "fea628c5-fa29-4f54-98ef-e4a2ede4d755",
"amount" : 0.00000000,
"currency" : "usd",
"type" : "ORIGINAL",
"alignable" : true
}
3. Initialize Payment
Endpoint:
POST acquiring/invoice/payment
Initializes the payment for the IBAN opening.
Body Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceId | string | ✅ | the invoice ID. |
type | string | ✅ | Payment provider type (only PLATFORM one is available). |
accountId | string | ✅ | Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint. |
currency | string | ✅ | Currency used for the payment. |
anyCurrency | boolean | ✅ | Flag indicating whether multiple currencies are supported. |
Response Example:
{
"accountId" : "59341629-5f86-47a5-a867-1c4225f119b0",
"id" : "8caf4504-d6b0-461b-9b67-53dacee85156",
"invoiceId" : "a90f36dd-57af-4f5e-a2f5-086631f9edac",
"status" : "INIT",
"type" : "PLATFORM",
"amount" : 15,
"description" : "Invoice payment",
"last_modified_date" : "2025-04-07T21:32:11.716207540Z",
"created_date" : "2025-04-07T21:32:11.716207540Z"
}
4. Confirm Invoice Payment
Endpoint:
POST acquiring/invoice/payment/pay
Confirms payment of the invoice.
Body Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceId | string | ✅ | the invoice ID. |
type | string | ✅ | Payment provider type (only PLATFORM one is available). |
paymentId | string | ✅ | Unique identifier for the payment from Step 4. |
accountId | string | ✅ | Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint. |
currency | string | ✅ | Currency used for the payment. |
anyCurrency | boolean | ✅ | Flag indicating whether multiple currencies are supported. |
Response Example:
{
"accountId" : "59341629-5f86-47a5-a867-1c4225f119b0",
"id" : "8caf4504-d6b0-461b-9b67-53dacee85156",
"invoiceId" : "a90f36dd-57af-4f5e-a2f5-086631f9edac",
"status" : "PROCESSING",
"type" : "PLATFORM",
"amount" : 15,
"description" : "Invoice payment",
"last_modified_date" : "2025-04-07T21:32:14.700515749Z",
"created_date" : "2025-04-07T21:32:11.716208Z"
}
5. Retrieve User's IBAN Info
Endpoint:
Retrieves the status of an IBAN issuance request. Upon successful issuance, the response includes the generated IBAN and linked bank account details.
Response Example:
{
"id": "00a386f2-6ca3-4e00-ba0a-4feef6af4c5d",
"type": "SEPA",
"bankName": "SETTLEGO SOLUTIONS LTD",
"bankAddress": "THE BOWER BUILDING 207 - 211 OLD STREET SHOREDITCH, LONDON",
"swiftBic": "SEOUGB21",
"accountNumber": "GB30SEOU19870010355854",
"accountHolderName": "John Mock-Doe",
"accountHolderAddress": "ES, 12345, Test city, Test Address 1",
"currency": "EUR",
"status": "ACTIVE",
"accountId": "e6542559-a837-4da0-8204-8183b317f250",
"invoiceId": null,
"memo": null,
"balance": 8.98000000000000000000
}
Request Statuses
| Status | Description |
|---|---|
INIT | Request is been completed but not yet paid. |
PENDING | Request pending review. |
SUPPORT | The IBAN issuance request could not be processed. For further assistance, please reach out to our support team. |
ACTIVE | IBAN is opened, top-up and withdrawal operations can be performed. |
CANCELLED | The user has cancelled the IBAN issuance request. |
CLOSED | The IBAN account is closed. |
INVOICE_FAILED | The invoice payment has failed. User should verify payment details and submit again. |
BLOCKED | The IBAN was blocked by the issuing provider. Contact support for resolution. |
The IBAN issuance request can be cancelled via POST v1/bank-accounts/{bankAccountId}/cancel endpoint while the status of the request is one of: INIT, SUPPORT, INVOICE_FAILED.
Once the IBAN is opened, the user can top up funds and make withdrawals . Note that all withdrawals require manual approval — the user will receive an email to confirm each transaction.
Updated 16 days ago