Guides

Payin API Guide

This guide provides detailed instructions for integrating a payment processing API. It includes essential endpoints for initiating payments and managing payment results.

Suggest Edits

❗️

Deprecation Notice:

The new enhanced guide is now available. Please migrate to the latest version, as the current one will be deprecated on 2025.07.28. Check the latest version

Before using the feature:

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

Step 1. 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:

NameTypeRequiredDescription
dryRunboolean➖This parameter allows to check resulting rate and fee amount without executing any operation. If true, the API simulates the operation without executing it. This allows you to preview exchange rates, fees, and other details before committing. The actual operation will only proceed if dryRun is omitted or explicitly set to false.

Body Parameters:

NameTypeRequiredDescription
accountuuid✅Identifier of the CHECKING- type account associated with the payin.
fromCurrencystring➖The original currency of the amount before conversion. Defaults to USD
toCurrencystring✅The destination currency after conversion.
fromAmountstring➖The amount in the source currency.

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 2. Create an Invoice Payment

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

Endpoint:

POST /invoice/payment

Body Parameters:

NameTypeRequiredDescription
invoiceIdstring✅Use the invoiceId obtained from the previous step.
typestring✅Payment provider type.
returnUrlstringThe link to redirect the user from Checkout page.

📌

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:

{
    "authLink": "https://pay.sandbox.checkout.com/link/pl_vMF29m5IEeHn",
    "returnUrl": "https://platform-api.dev.testessential.net/acquiring/payment/checkout/redirect",
    "id": "f8fcd954-ab97-4f20-8ff5-8c4aad7f9e40",
    "invoiceId": "01a97876-8889-4fe7-81b8-640ccb11ea5a",
    "status": "INIT",
    "type": "CHECKOUT",
    "amount": 15.38,
    "description": "invoice payment",
    "statusDescription": "initialized",
    "last_modified_date": "2025-06-02T09:57:30.131184360Z",
    "created_date": "2025-06-02T09:57:28.983612080Z"
}

Step 3. 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.

Updated 2 days ago