Guides

Exchange with withdraw (receive fiat) [Private]

Exchange cryptocurrency assets to EUR and withdraw them to a bank card (OffRamp).

Suggest Edits
Method name:/v2/exchange/external/withdraw-with-exchange
Request type:POST

📘

To call private endpoints, you need to get a JWT token or an API key for authentication.

Here you can learn in detail how to successfully authenticate.

This endpoint is used to exchange cryptocurrency to fiat with next withdraw to a bank card.

Before making a request to /v2/exchange/external/withdraw-with-exchange, you should make a request to receive rateId to /v2/rate/freeze. This request allows you to "freeze" the exchange rate for a certain (defined by the settings) time.

At the same time, in order to receive a freeze rate as part of this type of transaction, it is required to specify the withdrawPaymentCode, since a withdraw to card is used after exchanging crypto-fiat.
The payment method, in addition to determining the cost of the exchange operation, also contains a list of required fields (fields) asked by the provider to ensure the successful execution of the payment.
Therefore, when performing a freeze rate (/v2/rate/freeze), it is enough to specify only the withdrawPaymentCode, and when performing an exchange operation (/v2/exchange/external/withdraw-with-exchange), you need to specify the withdrawPaymentCode together with the fields for this payment method.
The list of fields and their parameters are returned together with the payment method as a response to the request at /v2/exchange/external/pre-request.

Withdrawal of fiat currency will begin only after the successful exchange of cryptocurrency to fiat will happen and will be processed only if all the fields described in the pre-request are correctly transmitted to provider.

Withdraw with exchange can acquire the following statuses:

CreatedOperation created.
ProcessingOperation in processing.
OnHoldThe operation is blocked (for example, for checking AML).
DeclinedThe operation is rejected.
CompletedThe operation is successful

To provide information about the status of the operation, a callback service is implemented. The link for receiving callbacks should be provided in the Withdraw with exchange request.

The duration of execution of a Withdraw with exchange request depends on speed of fiat withdraw processing. Part of exchange is instant.

Information about the amount of operation fees will be indicated along with other operation details.

Data dictionary

NameTypeParameter typeRequiredRangeDescription
walletIdstringBODYYES-Unique identifier of customer wallet in KunaCore.
rateIdstringBODYYES-Freeze rate ID from Freeze rate for operations endpoint.
callbackUrlstringBODYNO-After the withdraw is completed, a POST request will be created to the callbackUrl.
externalIdstringBODYYES-Unique ID of operation in your system.
withdrawPaymentMethodstringBODYYES-Data object about the withdrawal method.
withdrawPaymentMethod.codestringBODYYES-Withdrawal method code from "Pre-request for exchange".
withdrawPaymentMethod.fieldsstringBODYYES-Required fields for the withdrawal method from "Pre-request for exchange" .

Exemplary request

const url = BASE_URL;
const path = "/v2/exchange/external/withdraw-with-exchange";

const body = {
  withdrawPaymentMethod: {
    fields: {
      email: "[email protected]",
      phone: "+380633222304",
      cardHolder: "Alex Smith",
      country: "FR",
      region: "Paris",
      city: "Paris",
      street: "Champ de Mars, 5 Av. Anatole France",
      postCode: "75007",
      ip: "177.25.25.399",
      userAgent:
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
      cardNumber: "4251250231100019",
      expiryDate: "09/27",
    },
    code: "payment_card_eur_europe",
  },
  walletId: "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",
  callbackUrl: "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97",
  externalId: "withdrawal-001",
  rateId: "f33d8c28-337b-4e5a-b920-6dbf7571ebff",
};

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${data.accessToken}` // data.accessToken - generated a JWT token via /v2/auth/login.
  },
  body: JSON.stringify(body),
};

fetch(url + path, options)
  .then((response) => response.json())
  .then((showResponse) => console.log(showResponse.data));

import requests

url = BASE_URL
path = "/v2/exchange/external/withdraw-with-exchange"
headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer " + data.accessToken # data.accessToken - generated a JWT token via /v2/auth/login.
}
body = {
  "withdrawPaymentMethod": {
    "fields": {
      "email": "[email protected]",
      "phone": "+380633222304",
      "cardHolder": "Alex Smith",
      "country": "FR",
      "region": "Paris",
      "city": "Paris",
      "street": "Champ de Mars, 5 Av. Anatole France",
      "postCode": "75007",
      "ip": "177.25.25.399",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
      "cardNumber": "4251250231100019",
      "expiryDate": "09/27"
    },
    "code": "payment_card_eur_europe"
  },
  "walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",
  "callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97",
  "externalId": "withdrawal-001",
  "rateId": "f33d8c28-337b-4e5a-b920-6dbf7571ebff"
}

request = requests.post(url + path, headers=headers, json=body)
print(request.json())

How to call private endpoints here

Swagger here

Response

{
  "data": {
    "address": null,                                                            // Always null for "Exchange with withdraw".
    "blockchainTxId": null,                                                     // Always null for "Exchange with withdraw".
    "callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97", // Link to the callback handler.
    "id": "f33d8c28-337b-4e5a-b920-6dbf7571ebff",                               // Internal operation ID.
    "memo": null,                                                               // Always null for "Exchange with withdraw".
    "createdAt": "2024-03-12T17:08:15.398Z",                                    // Operation сreation time.
    "feeDepositAsset": "USDT",                                                  // Not required for "Exchange with withdraw" request.
    "feeTradeAsset": "EUR",                                                     // Fee asset of trade.                                      
    "feeWithdrawAsset": "EUR",                                                  // Fee asset of withdrawal.
    "externalId": "withdrawal-001",                                             // External operation ID.
    "feeDeposit": "0",                                                          // Not required for "Exchange with withdraw" request.
    "feeTrade": "0.5",                                                          // Trade fee.
    "feeWithdraw": "0.2",                                                       // Withdrawal fee.
    "status": "Created",                                                        // Operation status.
    "network": null,                                                            // Not required for "Exchange with withdraw" request.
    "rate": "0.9751",                                                           // Exchange rate.
    "reason": null,                                                             // Reason for stopping the operation.
    "sourceAmount": "10.973234",                                                // Amount spent.
    "sourceAsset": "USDT",                                                      // Asset of the amount spent.
    "targetAmount": "10",                                                       // Amount received.
    "targetAsset": "EUR",                                                       // Asset of the amount received.
    "totalFeeSourceAsset": "0.717875",                                          // Total fees of the base (Source) asset. 
    "totalFeeTargetAsset": "0.7",                                               // Total fees of the quote (Target) asset. 
    "type": "WithdrawWithExchange",                                             // Operation type.
    "walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",                         // Customer wallet ID.
    "completedAt": null                                                         // Operation сompletion time.
  }
}

Callback example

You get a callback for each transaction status.

{
  "data": {
    "id": "f33d8c28-337b-4e5a-b920-6dbf7571ebff",
    "memo": null,
    "rate": "0.9751",
    "type": "WithdrawWithExchange",
    "reason": null,
    "status": "Created | OnHold | Processing | Completed | Declined",
    "address": null,
    "network": null,
    "feeTrade": "0.5",
    "metadata": {},
    "walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",
    "createdAt": "2024-03-12T17:08:15.398Z",
    "externalId": "withdrawal-001",
    "feeDeposit": "0",
    "callbackUrl": "https://webhook.site/#!/view/12495b92-cbe4-4e88-a645-19b1ae5f4c97/6d028644-8757-41f1-8f9f-66eb366b8d6c/1",
    "completedAt": "2024-03-12T17:08:32.321Z",
    "feeWithdraw": "0.2",
    "sourceAsset": "USDT",
    "targetAsset": "EUR",
    "sourceAmount": "10.973234",
    "targetAmount": "10",
    "feeTradeAsset": "EUR",
    "initialAmount": null,
    "blockchainTxId": null,
    "feeDepositAsset": "USDT",
    "feeWithdrawAsset": "EUR",
    "totalFeeSourceAsset": "0.717875",
    "totalFeeTargetAsset": "0.7"
  }
}

Updated 6 months ago