We offer IBAN cash-in to the GnosisPay Account via Monerium for users in Europe (EU) and Switzerland.

​
Check Availability

First you need to check if the user is available to activate their IBAN:
cURL
curl -X GET /api/v1/ibans/available
If you receive a "available": false, the flow ends here.
Requirements the User must have:

​
Enabling the IBAN Integration

1

Signing the Monerium message

Monerium requires a specific message to be signed by the User’s wallet. Use this endpoint get the exact message that needs to be signed:
cURL
curl -X GET /api/v1/ibans/signing-message
To request signature from your gnosis safe, you can follow this demo signature implementation.
We cannot request new IBANs nor transfer existing IBANs until the message signature is completed. This signature is a mandatory requirement from Monerium to verify ownership of the address.
2

Request the IBAN from Monerium

You need to call this endpoint to request your IBAN profile:
cURL
curl -X POST /api/v1/ibans/monerium-profile \
-d '{
  "signature": "... signed message as a string ...",
  "callbackUrl": "https://your-app.com/iban-callback"
}'
This endpoint can fail and it is expected: Monerium only allows the user to have one single account with them. If the user already has an account, this call will fail to indicate you should follow the oAuth flow with Monerium.
There are two results possible here:
  1. If the User is not registered with Monerium you will receive a "success": true and it will take 3+ minutes (due to the delay module that verifies the signature and ownership of the address) for the new Monerium account to be created;
  2. The user already has a Monerium profile, so we need to request access to it via an oAuth flow, in this case the request will fail as expected.
When your User already have a Monerium account, we need to redirect the user to a URL so they can allow GnosisPay to interact with their existing account. So the POST will return a 422 error with the following body:
{
  errors: {
    externalApiCallStatusCode: 304,
    message: "User needs to be redirect to Monerium oAuth flow",
    redirectUrl: "... url ...",
  },
}
You need to redirect your users when externalApiCallStatusCode == 304. After the User approves our access to their existing account, the background job will pick up from there and user will be redirected to the provided callback URL.Another way to get the redirect URL if user has Monerium profile already is to use the /api/v1/ibans/oauth/redirect_url endpoint.
callbackUrl should always be sent as query parameter in both the cases.
3

Get the IBAN number, BIC, Status and Connected Blockchain Address where funds are sent

You should monitor this endpoint until you see a status of ASSIGNED:
cURL
curl -X GET /api/v1/ibans/details
Use this data to cash-in to your GnosisPay Account.
IBAN StatusDescriptionAction
NOTSTARTEDInitial state when the user hasn’t started the IBAN creation process yetUser needs to initiate the IBAN creation process
PENDINGIBAN creation has been initiated and is being processed by MoneriumWait for the process to complete, periodically check the status
PENDING_OAUTHUser has an existing Monerium profile and needs to authorize GnosisPay via OAuthRedirect the user to the OAuth URL provided in the response
ASSIGNEDIBAN has been successfully created and assigned to the userIBAN is ready to use for cash-in transactions
4

Get the IBAN Statement (Orders list)

To get a complete statement for the orders processed through IBAN:
cURL
curl -X GET /api/v1/ibans/orders
This endpoint returns only incoming orders (deposits) to the user’s IBAN.

​
Message Signing Example with GnosisPay Account Kit

You can use the GnosisPay Account Kit as example to generate a signature for endpoint. You can find the Account Kit code in our GitHub repository.

​
Example Usage

import { Wallet } from 'ethers';
import {
  populateExecuteEnqueue,
  predictAccountAddress,
  createInnerSignMessageTransaction
} from '@gnosispay/account-kit';

// Initialize your wallet
const wallet = new Wallet(privateKey, provider);

// Predict the account address
const owner = wallet.address;
const safeAddress = predictAccountAddress({ owner });

// Create a transaction to sign a message
const transaction = createInnerSignMessageTransaction(
  "I hereby declare that I am the address owner."
);

// Generate the execute transaction with signature
const enqueueTx = await populateExecuteEnqueue(
  { account: safeAddress, chainId: 100 },
  transaction,
  ({ domain, types, message }) => wallet._signTypedData(domain, types, message)
);

// The transaction data contains the signature
console.log(enqueueTx.data, '-> signature');
Note:
  • The message can be fetched from the API using GET /api/v1/ibans/signing-message
  • The generated transaction can be submitted to prove ownership
  • Make sure to use the correct chainId (100 for Gnosis Chain)