Buy crypto to send to address [Private]
External fiat deposit with exchange by fixed rate and send crypto to external address.
| Method name: | /v2/exchange/external/buy-to-send-crypto |
| 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 a combination of two other endpoints in one operation - /v2/exchange/external/deposit-with-exchange and /v2/withdraw/crypto.
This allows you to exchange EUR paid using a bank card for crypto and simultaneously (without calling a separate endpoint) withdraw the received cryptocurrency to the specified crypto address.
For the endpoint, the conditions of execution are valid, which are valid for separately taken endpoints of deposit with exchange and withdrawal.
So, before making a request to /v2/exchange/external/buy-to-send-crypto, you must send 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 depositPaymentCode AND also withdrawPaymentCode, since a deposit by card and withdraw to crypto address is used.
The payment methods, in addition to determining the cost of the exchange operation, also contains a list of required fields (fields) asked by the provider (for deposit) and by the blockchain (for withdraw) to ensure the successful execution of the payment.
Therefore, when performing a freeze rate (/v2/rate/freeze), it is enough to specify only the depositPaymentCode and withdrawPaymentCode, but when performing an exchange operation (/v2/exchange/external/buy-to-send-crypto), you need to specify the depositPaymentCode and withdrawPaymentCode together with the fields for this payment methods.
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.
Provided that all data for creating an invoice have been correctly transmitted, a link to the payment of this invoice or bearerToken (for payment without payment link) will be returned in metadata.invoice object the response to the request to /v2/exchange/external/buy-to-send-crypto. The operation will be continued only after the client pays the invoice, after which the stage of exchanging fiat currency for crypto will begin.
After the exchange and a successful AML check, the received cryptocurrency will be withdrawn to a crypto address, provided that the data is correct and sufficient for such a withdrawal (correct crypto address, memo sign, etc.).
Deposit with exchange can acquire the following statuses:
| Created | Operation created. |
| Processing | Operation in processing. |
| OnHold | The operation is blocked (for example, for checking AML). |
| Declined | The operation is rejected. |
| Completed | The 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 request to /v2/exchange/external/buy-to-send-crypto.
The duration of execution of that type of operation depends on the speed of execution of its separated parts -speed of fiat deposit, speed of fiat to crypto exchange and speed of crypto withdrawal. Execution of a crypto withdrawal depends on many factors, but the main one is the speed of processing such withdrawal by the blockchain network. In most cases, this is a few minutes, but sometimes the processing time can take much longer. Part of exchange fiat to crypto is instant.
Information about the amount of operation fees will be indicated along with other operation details.
Data dictionary
| Name | Type | Parameter type | Required | Range | Description |
|---|---|---|---|---|---|
| walletId | string | BODY | YES | - | Unique identifier of customer wallet in KunaCore. |
| rateId | string | BODY | YES | - | Freeze rate ID from Freeze rate for operations endpoint. |
| callbackUrl | string | BODY | NO | - | After the withdraw is completed, a POST request will be created to the callbackUrl. |
| externalId | string | BODY | YES | - | Unique ID of operation in your system. |
| withdrawPaymentMethod | string | BODY | YES | - | Data object about the withdrawal method. |
| withdrawPaymentMethod.code | string | BODY | YES | - | Withdrawal method code from "Pre-request for exchange". |
| withdrawPaymentMethod.fields | string | BODY | YES | - | 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
Response
{
"data": {
"address": "T9zGcAgLTSQdwqiebc4miqreaUZ68HrhiF", // Cryptocurrency withdrawal address.
"blockchainTxId": null, // Withdrawal transaction hash.
"callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97", // Link to the callback handler.
"id": "41c039a2-0efd-4f8a-9015-b60a1c668d27", // Internal operation ID.
"memo": null, // Memo of the cryptocurrency withdrawal address
"createdAt": "2024-03-13T17:22:32.664Z", // Operation сreation time.
"feeDepositAsset": "EUR", // Fee asset of deposit.
"feeTradeAsset": "USDT", // Fee asset of trade.
"feeWithdrawAsset": "USDT", // Fee asset of withdrawal.
"externalId": "but-send-001", // External operation ID.
"feeDeposit": "0.15", // Deposit fee.
"feeTrade": "0", // Trade fee.
"feeWithdraw": "0", // Withdrawal fee.
"status": "Created", // Operation status.
"network": null, // Cryptocurrency withdrawal address network.
"rate": "1.015332", // Exchange rate.
"reason": null, // Reason for stopping the operation.
"sourceAmount": "15", // Amount spent.
"sourceAsset": "EUR", // Asset of the amount spent.
"targetAmount": "15.07768", // Amount received.
"targetAsset": "USDT", // Asset of the amount received.
"totalFeeSourceAsset": "0.15", // Total fees of the base (Source) asset.
"totalFeeTargetAsset": "0.1523", // Total fees of the quote (Target) asset.
"type": "BuyToSendCrypto", // Operation type.
"walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5", // Customer wallet ID.
"completedAt": null, // Operation сompletion time.
"metadata": {
"invoice": {
"sid": "cgi_QChy5LLPwYH7wRUS", // Internal operation ID.
"token": "eyJ0eXAiOiJKV1QiLCDM...Q9-HbYLqmYoFOzicAHo8doHNkYZTmuhNM", // Token for "host-to-host" depost.
"action": "https://checkout.speedpayment.net/hpp/cgi_QChy5LLPwYH7wRUS", // Invoice payment link.
"method": "GET", // Method for "action" field.
"params": [] // Additional parameters for the request with the "action" field.
}
}
}
}
Callback example
You get a callback for each transaction status.
{
"data": {
"id": "41c039a2-0efd-4f8a-9015-b60a1c668d27",
"memo": null,
"rate": "1.015332",
"type": "BuyToSendCrypto",
"reason": null,
"status": "Created | OnHold | Processing | Completed | Declined",
"address": "T9zGcAgLTSQdwqiebc4miqreaUZ68HrhiF",
"network": null,
"feeTrade": "0",
"metadata": {},
"walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",
"createdAt": "2024-03-13T17:22:32.664Z",
"externalId": "but-send-001",
"feeDeposit": "0.15",
"callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97",
"completedAt": "2024-03-13T17:39:58.949Z",
"feeWithdraw": "0",
"sourceAsset": "EUR",
"targetAsset": "USDT",
"sourceAmount": "15",
"targetAmount": "15.07768",
"feeTradeAsset": "USDT",
"initialAmount": null,
"blockchainTxId": null,
"feeDepositAsset": "EUR",
"feeWithdrawAsset": "USDT",
"totalFeeSourceAsset": "0.15",
"totalFeeTargetAsset": "0.1523"
}
}
Updated 6 months ago