Deposit with exchange (pay by fiat) [Private]
Deposit fiat assets and exchange for cryptocurrency assets (OnRamp).
| Method name: | /v2/exchange/external/deposit-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 receive cryptocurrency by paying it in fiat using a bank card or SEPA transfer.
Before making a request to /v2/exchange/internal/crypto, you must 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.
It is important to note that the freeze rate for this type of exchange, which is carried out using the SEPA transfer deposit method, is indicative at the moment the request is made to initiate the operation. The exact freeze rate will be recalculated at the moment the euro deposit is actually credited to the user's account for further exchange.
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, since a deposit by card or SEPA transfer is used when exchanging fiat-crypto.
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 depositPaymentCode, and when performing an exchange operation (/v2/exchange/external/deposit-with-exchange), you need to specify the depositPaymentCode 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.
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, integration guide here https://merchant.kuna.io/docs/ru/integration/payments/h2h/#card-gate) will be returned in metadata.invoice object the response to the request to /v2/exchange/external/deposit-with-exchange. The operation will be continued only after the client pays the invoice, after which the stage of exchanging fiat currency for crypto will begin.
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 Deposit with exchange request.
The duration of execution of a Deposit with exchange depends on speed of fiat deposit processing. Fiat deposit made using a bank card may take a few moments, while a SEPA transfer can take up to 3-5 days. Part of exchange 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 /v2/rate/freeze endpoint. |
| callbackUrl | string | BODY | NO | - | After the exchange is completed, a POST request will be created to the callbackUrl. |
| externalId | string | BODY | YES | - | Unique ID of operation in your system. |
| returnUrl | string | BODY | NO | - | URL to redirect customer after successful payment. |
| depositPaymentMethod | string | BODY | YES | - | Data object about a deposit payment method. |
| depositPaymentMethod.code | string | BODY | YES | - | Payment method code from "Pre-request for exchange". |
| depositPaymentMethod.fields | string | BODY | YES | - | Required fields for payment method from "Pre-request for exchange" . |
Exemplary request
const url = BASE_URL;
const path = "/v2/exchange/external/deposit-with-exchange";
const body = {
depositPaymentMethod: {
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',
description: 'Deposit of my own funds',
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'
},
code: 'payment_card_eur_hpp_europe'
},
walletId: '1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5',
callbackUrl: 'https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97',
externalId: '01-02-001',
returnUrl: 'https://my-site.com/successful-payment-page',
rateId: '77db4f0e-07c5-408b-8e61-4e696b2fb879'
};
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/deposit-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 = {
"depositPaymentMethod": {
"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",
"description": "Deposit of my own funds",
"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"
},
"code": "payment_card_eur_hpp_europe"
},
"walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",
"callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97",
"externalId": "01-02-001",
"returnUrl": "https://my-site.com/successful-payment-page",
"rateId": "77db4f0e-07c5-408b-8e61-4e696b2fb879"
}
request = requests.post(url + path, headers=headers, json=body)
print(request.json())
How to call private endpoints here
Response
{
"data": {
"address": null, // Always null for "Deposit with exchange".
"blockchainTxId": null, // Always null for "Deposit with exchange".
"callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97", // Link to the callback handler.
"id": "77db4f0e-07c5-408b-8e61-4e696b2fb879", // Internal operation ID.
"memo": null, // Always null for "Deposit with exchange".
"createdAt": "2024-03-08T17:33:39.906Z", // Operation сreation time.
"feeDepositAsset": "EUR", // Fee asset of deposit.
"feeTradeAsset": "USDT", // Fee asset of trade.
"feeWithdrawAsset": "USDT", // Not required for "Deposit with exchange" request.
"externalId": "01-02-001", // External operation ID.
"feeDeposit": "0.1", // Depost fee.
"feeTrade": "0", // Trade fee.
"feeWithdraw": "0", // Not required for "Deposit with exchange" request.
"status": "Created", // Operation status.
"network": null, // Exchange rate.
"rate": "0.94767", // Not required for "Deposit with exchange" request.
"reason": null, // Reason for stopping the operation.
"sourceAmount": "10", // Amount spent.
"sourceAsset": "EUR", // Asset of the amount spent.
"targetAmount": "9.381933", // Amount received.
"targetAsset": "USDT", // Asset of the amount received.
"totalFeeSourceAsset": "0.1", // Total fees of the base (Source) asset.
"totalFeeTargetAsset": "0.094767", // Total fees of the quote (Target) asset.
"type": "DepositWithExchange", // Operation type.
"walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5", // Customer wallet ID.
"metadata": {
"invoice": {
"sid": "cgi_UKziQKV7aOw6ufK3", // Internal operation ID.
"token": "eyJ0eXAiOiJKV1QiLCJhbPMzq...AdA7CfVIQk6AePIj6GnLSW2ucuO_6LvVU", // Token for "host-to-host" depost.
"action": "https://checkout.speedpayment.net/hpp/cgi_UKziQKV7aOw6ufK3", // 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": "77db4f0e-07c5-408b-8e61-4e696b2fb879",
"memo": null,
"rate": "0.94767",
"type": "DepositWithExchange",
"reason": null,
"status": "Created | OnHold | Processing | Completed | Declined",
"address": null,
"network": null,
"feeTrade": "0",
"metadata": {},
"walletId": "1f44b1c7-9fd4-4d20-b9a4-7aca3646d0d5",
"createdAt": "2024-03-08T17:33:39.906Z",
"externalId": "01-02-001",
"feeDeposit": "0.1",
"callbackUrl": "https://webhook.site/12495b92-cbe4-4e88-a645-19b1ae5f4c97",
"completedAt": "2024-03-08T17:35:19.194Z",
"feeWithdraw": "0",
"sourceAsset": "EUR",
"targetAsset": "USDT",
"sourceAmount": "10",
"targetAmount": "9.381933",
"feeTradeAsset": "USDT",
"initialAmount": null,
"blockchainTxId": null,
"feeDepositAsset": "EUR",
"feeWithdrawAsset": "USDT",
"totalFeeSourceAsset": "0.1",
"totalFeeTargetAsset": "0.094767"
}
}
Updated about 2 months ago