iDEAL in3 Developer Api documentation

• Client: Payment Service Provider (PSP)
• Customer: The user of the Shop that wants to purchase a service/good
• Merchant: Customer of the Client which owns shops or points of sale. The entity that is billed for iDEAL in3's services
• Shop: Point of sale that belongs to a Merchant

If you have any questions regarding the integration with our Api, please contact one of the following:

Development:

• Email: contact@scenius.nl
• Telephone: 040 - 369 0149

Merchant/Shop/Customer:

• Email: support@in3.ideal.nl
• Telephone: 088 - 39 93 333

iDEAL in3 only accepts customers based in the Netherlands.

Note: Merchants can be onboarded as longs as they deliver to The Netherlands!

At iDEAL in3, we have a minimum and a maximum amount for an order you can make.

Minimum: 50€

Maximum: 5000€

For merchant onboarding iDEAL in3 provides two flows, namely:

• Ahead of time onboarding (Preferred)
• Inline onboarding (Legacy)

Before starting integration with iDEAL in3, check if all legal documents (KYC checks) and merchant contracting are covered in your onboarding!

With this onboarding method the merchant will be onboarded before the first iDEAL in3 order/transaction has been made. This will require the Client to implement the onboarding API calls separately from the transaction calls and keep track of iDEAL in3's onboarding state. This method has our preference.

This method of onboarding is preferred way of integrating with iDEAL in3.

With this onboarding method, the merchant will be onboarded before the first iDEAL in3 order (transaction) has been made. This will require the client to implement the onboarding API calls separately from the transaction calls and keep track of iDEAL in3`s state.

You (PSP) will call iDEAL in3 with [POST Create a merchant] all information from merchant. After you do this call you will receive Creation result as response. Depending on that Creation result you will need to do call to [POST Create a shop] endpoint. You will need to call this method multiple times if merchant has multiple shops. Important step in flow is to call method [GET Get onboarding status]. Depending on response from iDEAL in3 on this method you can have multiple alternative flows. PENDING flow, REJECTED flow, ACTIVE flow. Only when response to [GET Get onboarding] status is ACTIVE then user can initiate flow to start transaction. From PSP side this is done by calling [POST Start transaction]. Please also insure to implement webhook for receiving status in step "Report onboarding status".

Additional important information:

Please provide these fields in [POST Create a merchant] and [POST Create a shop] calls in order to SKIP implementing PENDING state.

• Create a Merchant: IBAN and Ascription fields are only required for Gateway solutions
• Create a Merchant: Only authorized Contact(s) field is required
• Create a Merchant: variableFee and fixedFee are nice to have
• Create a Shop: Categories field is best case. If available please provide a list so that we can make a mapping. MCC list is the preferred list to put here.
• Create a Shop: Expected traffic is optional unless otherwise specified by iDEAL in3
• Create a Shop: Platform is optional

This is a NOT preferred method of onboarding, and it is considered Legacy. iDEAL in3 recommends to use the "Ahead of time onboarding" method, as this (inline onboarding) method can cause inconvenience to the merchant.

Important information: The "initial/first" customer will be able to complete the order as expected. iDEAL in3 will also report "PAID", but iDEAL in3 will not pay out the PSP for the completed order until [POST Order onboarding] is completed.

You can use the payment option iDEAL in3 if your webshop / sales location falls into one of the categories below.

Start a new in3 transaction

Total captured amount across all capture requests must not exceed the originally authorized transaction amount.
Multiple partial captures are allowed.
Transactions without capture after a defined window (e.g., 30 days) may expire automatically.

The following endpoints support seamless boarding also referred to as 'Ahead of time Onboarding'.

Get informed when something relevant changes. Here you can setup which URL we should inform. All webhooks only inform you of the changed ID's so that you can fetch the latest status yourself completing the triangle.

Confirming HMAC on the receiving side of the webhook is as following:

• Combine the full response body with the unix timestamp from the response header: "hmac_date", and seperate them with a semicolon. {"key":"value"};1646147678
• Encrypt the following value fully with SHA512, using the signing key from the creation request.
• If the result hash equals the hmac from the response header, you have a valid HMAC.

/// <summary>
/// Verifies HMAC from webhook
/// </summary>
/// <param name="hmac">Hmac header</param>
/// <param name="hmacDate">Hmac_date header</param>
/// <param name="jsonBody">The full response body</param>
/// <param name="signingKey">The signing key that was transmitted on the creation of the webhook.</param>
/// <returns></returns>
public bool VerifyHmac(string hmac, long hmacDate, string jsonBody, string signingKey)
{
    if (DateTimeOffset.FromUnixTimeSeconds(hmacDate) > DateTimeOffset.Now.AddMinutes(15))
    {
        // Timestamp in HMAC is too old, or modified.
        return false;
    };

    var payload = $"{jsonBody};{hmacDate}";
    
    var signingKeyDecoded = Convert.FromBase64String(signingKey);

    var signature = string.Empty;
    using (var hmacsha512 = new HMACSHA512(signingKeyDecoded))
    {
        var stream = new MemoryStream(Encoding.UTF8.GetBytes(payload));
        foreach (var b in hmacsha512.ComputeHash(stream))
        {
            signature = signature + $"{b:x2}";
        }
    }

    return hmac == signature;
}