Before using the feature:

1. Complete KYC.
2. Purchase a subscription plan , which includes the payin function.

Step 1. Add Payment Cards

POST /acquiring/v1/payin/cards

This endpoint is used to save payment cards details. Users are limited to storing a maximum of 4 payment cards.

Body Parameters:

The list of states to specify in the state field can be retrieved by using Retrieve State List endpoint.

Response Example:

{
    "cardId": "f37cdbe7-04af-4390-8716-d9ab751111ec",
    "maskedPan": "411111****1111",
    "cardCompany": "Visa",
    "countryCode": "PL"
}

The list of saved payment cards can be retrieved by using Get list of saved cards endpoint. To delete a saved card use Delete Card endpoint.

Step 2. Optional: Integrate with Checkout Risk SDK

Payin transactions are processed through the external partner. Integrate with Checkout Risk SDK before making further API calls. How to integrate

While integration is not mandatory, we strongly recommend implementing this feature, as it significantly increases transaction approval rates from Checkout.

Step 3. Initiate a Payin Operation

Endpoint:

POST /wallet/payin

The endpoint initiates a payin operation to deposit funds in the specified currency to the user's account.

Query Parameters:

Body Parameters:

The account parameter can be retrieved by using List all accounts endpoint.

Response Example:

{
    "id": "7e5a8755-1cda-4ed0-8405-aa762d90af4d",
    "invoiceId": "8c065183-d6eb-415b-95b7-2a85c13312dd",
    "account": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
    "fromCurrency": "USD",
    "toCurrency": "ETH",
    "fromAmount": "20.00",
    "toAmount": "0.007373800000000000",
    "feeAmount": "0.00",
    "feeCurrency": "USD",
    "signedRate": {
        "rateRequest": {
            "fromCurrency": "USD",
            "toCurrency": "ETH",
            "amount": 0,
            "account": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
            "partner": "Wafee"
        },
        "rate": 0.00036869,
        "feeConfig": {
            "feePercent": 0.025
        },
        "minFromAmount": 5.53,
        "maxFromAmount": 4901.96,
        "minToAmount": 0.00200000,
        "maxToAmount": 1.84349134,
        "exchangeRoute": {
            "routeElements": [
                {
                    "fromCurrency": "USD",
                    "toCurrency": "ETH",
                    "exchange": "kraken",
                    "rate": 0.000376222723852520
                }
            ]
        },
        "validUntil": "2025-06-06T15:25:42.313Z",
        "signature": "eNc9k1YWqPYcM7NiZ7t+FpTHXIMIgt5ssToBY3XS/FeHHtZ0rzC2wtGHpKk4ExNZih1usxfOBYyoJUe25C5nOwiVd/5Yy74RsEIE3F12ed+rNnNzpeiNY+EubsAXm1lQCOYdap/Iq3fZX1P218oTDVcGh1TEgB2kSgT4aDzFtqmb9TMKIN0LzEBBVVM3hvunbc+fx76fShuOkG2SQRyZYq6arjWyioxR/W4Wz1bbq0CyTsLbzPXtS6otUtV1wkJxQ228UKUz1JVc02gUQ+/9oxyyYEmPKjSCwB0TZdHnnfcgYjXS+kb50DVrLSZeEZVoNwoDKkp8B8/nA5Xf/02IEg=="
    },
    "status": "PENDING",
    "createdAt": "2025-06-06T15:24:57.388913443Z",
    "updatedAt": "2025-06-06T15:24:57.639762368Z"
}

The id and invoiceId fields values will only be returned in the response if dryRun parameter is set to false.

Step 4. Create an Invoice Payment

On this step the user gets the link to the Checkout page — it is retrieved in authLink parameter.

We do not store CVV codes on our servers — you must collect the CVV from the user each time a transaction is performed.

Endpoint:

POST /acquiring/v2/invoice/payin/pay

Body Parameters:

📌

For the type parameter, select the value CHECKOUT

The type parameter is central to the payment process, defining how payments are handled. It influences API endpoint behavior and determines required request fields. Correctly implementing this parameter ensures seamless integration and accurate processing for the chosen payment method.

CHECKOUT type indicates that payments are processed through an external checkout interface. Users are redirected to a payment gateway or external interface.

Request Example:

{
  "invoiceId": "0467205c-e8ec-4a06-9d84-461de663d374",
  "type": "CHECKOUT"
}

Response Example:

{
    "id": "fe747b0e-732d-4ece-9b8b-3873b1973e77",
    "invoiceId": "70803d78-f7b5-4e01-84d8-cb06d5d48444",
    "status": "INIT",
    "authLink": "https://authentication-devices.sandbox.checkout.com/sessions-interceptor/sid_jbtwoswtavfebebxyarxm65nmm",
    "returnUrl": "https://platform-api.dev.testessential.net/acquiring/payment/checkout/redirect",
    "amount": 25.00,
    "createdDate": "2025-06-19T14:44:02.488914397Z"
}

Step 5. Checkout and redirect

Redirect the user to the Checkout page using the authLink provided in the previous step. There, the user can enter the required information and complete the payment.

Once the payment is successful, the user will be automatically redirected to the URL specified in the returnUrl parameter.

You can check the operation result via the Retrieve a payin by ID endpoint.