Create a fiat-to-crypto payment session
curl --request POST \
--url https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"inAmount": "100.00",
"inCurrency": "EUR",
"outCryptocurrency": "USDC",
"callbackUrl": "https://example.com/webhooks/pay-in",
"successRedirectUrl": "https://example.com/pay-in/success",
"failureRedirectUrl": "https://example.com/pay-in/failure",
"externalRef": "order-67890",
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'import requests
url = "https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions"
payload = {
"inAmount": "100.00",
"inCurrency": "EUR",
"outCryptocurrency": "USDC",
"callbackUrl": "https://example.com/webhooks/pay-in",
"successRedirectUrl": "https://example.com/pay-in/success",
"failureRedirectUrl": "https://example.com/pay-in/failure",
"externalRef": "order-67890",
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
inAmount: '100.00',
inCurrency: 'EUR',
outCryptocurrency: 'USDC',
callbackUrl: 'https://example.com/webhooks/pay-in',
successRedirectUrl: 'https://example.com/pay-in/success',
failureRedirectUrl: 'https://example.com/pay-in/failure',
externalRef: 'order-67890',
idempotencyKey: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
})
};
fetch('https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'inAmount' => '100.00',
'inCurrency' => 'EUR',
'outCryptocurrency' => 'USDC',
'callbackUrl' => 'https://example.com/webhooks/pay-in',
'successRedirectUrl' => 'https://example.com/pay-in/success',
'failureRedirectUrl' => 'https://example.com/pay-in/failure',
'externalRef' => 'order-67890',
'idempotencyKey' => '3fa85f64-5717-4562-b3fc-2c963f66afa6'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions"
payload := strings.NewReader("{\n \"inAmount\": \"100.00\",\n \"inCurrency\": \"EUR\",\n \"outCryptocurrency\": \"USDC\",\n \"callbackUrl\": \"https://example.com/webhooks/pay-in\",\n \"successRedirectUrl\": \"https://example.com/pay-in/success\",\n \"failureRedirectUrl\": \"https://example.com/pay-in/failure\",\n \"externalRef\": \"order-67890\",\n \"idempotencyKey\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inAmount\": \"100.00\",\n \"inCurrency\": \"EUR\",\n \"outCryptocurrency\": \"USDC\",\n \"callbackUrl\": \"https://example.com/webhooks/pay-in\",\n \"successRedirectUrl\": \"https://example.com/pay-in/success\",\n \"failureRedirectUrl\": \"https://example.com/pay-in/failure\",\n \"externalRef\": \"order-67890\",\n \"idempotencyKey\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inAmount\": \"100.00\",\n \"inCurrency\": \"EUR\",\n \"outCryptocurrency\": \"USDC\",\n \"callbackUrl\": \"https://example.com/webhooks/pay-in\",\n \"successRedirectUrl\": \"https://example.com/pay-in/success\",\n \"failureRedirectUrl\": \"https://example.com/pay-in/failure\",\n \"externalRef\": \"order-67890\",\n \"idempotencyKey\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": {
"id": "5e6f7081-92a3-4b4c-8d5e-6f708192a3b4",
"accountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
"status": "CREATED",
"inAmount": 100,
"inCurrency": "EUR",
"outCryptocurrency": "USDC",
"paymentUrl": "https://pay.example.com/session/5e6f708192a3b4c8",
"externalRef": "order-67890",
"walletId": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
"blockchainTxId": null,
"cancellable": true,
"expiresAt": "2026-01-15T10:30:00Z",
"metadata": {
"orderId": "67890"
},
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2026-01-15T09:30:00Z",
"updatedAt": "2026-01-15T09:30:00Z"
}
}{
"success": false,
"errors": [
{
"code": "no-suitable-provider",
"message": "No enabled pay-in provider supports EUR to USDC."
}
]
}{
"success": false,
"errors": [
{
"code": "unauthenticated",
"message": "Please authenticate to perform this action."
}
]
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": "kyc-required",
"message": "Account {accountId} KYC status is not verified"
}
]
}{
"success": false,
"errors": [
{
"code": "internal-error",
"message": "An unexpected error occurred. Please try again later."
}
]
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}Fiat to Crypto Payment Sessions
Create a pay-in session
Start a hosted fiat-to-crypto pay-in and get a payment URL.
POST
/
accounts
/
{accountId}
/
fiat-to-crypto
/
payment-sessions
Create a fiat-to-crypto payment session
curl --request POST \
--url https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"inAmount": "100.00",
"inCurrency": "EUR",
"outCryptocurrency": "USDC",
"callbackUrl": "https://example.com/webhooks/pay-in",
"successRedirectUrl": "https://example.com/pay-in/success",
"failureRedirectUrl": "https://example.com/pay-in/failure",
"externalRef": "order-67890",
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'import requests
url = "https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions"
payload = {
"inAmount": "100.00",
"inCurrency": "EUR",
"outCryptocurrency": "USDC",
"callbackUrl": "https://example.com/webhooks/pay-in",
"successRedirectUrl": "https://example.com/pay-in/success",
"failureRedirectUrl": "https://example.com/pay-in/failure",
"externalRef": "order-67890",
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
inAmount: '100.00',
inCurrency: 'EUR',
outCryptocurrency: 'USDC',
callbackUrl: 'https://example.com/webhooks/pay-in',
successRedirectUrl: 'https://example.com/pay-in/success',
failureRedirectUrl: 'https://example.com/pay-in/failure',
externalRef: 'order-67890',
idempotencyKey: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
})
};
fetch('https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'inAmount' => '100.00',
'inCurrency' => 'EUR',
'outCryptocurrency' => 'USDC',
'callbackUrl' => 'https://example.com/webhooks/pay-in',
'successRedirectUrl' => 'https://example.com/pay-in/success',
'failureRedirectUrl' => 'https://example.com/pay-in/failure',
'externalRef' => 'order-67890',
'idempotencyKey' => '3fa85f64-5717-4562-b3fc-2c963f66afa6'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions"
payload := strings.NewReader("{\n \"inAmount\": \"100.00\",\n \"inCurrency\": \"EUR\",\n \"outCryptocurrency\": \"USDC\",\n \"callbackUrl\": \"https://example.com/webhooks/pay-in\",\n \"successRedirectUrl\": \"https://example.com/pay-in/success\",\n \"failureRedirectUrl\": \"https://example.com/pay-in/failure\",\n \"externalRef\": \"order-67890\",\n \"idempotencyKey\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inAmount\": \"100.00\",\n \"inCurrency\": \"EUR\",\n \"outCryptocurrency\": \"USDC\",\n \"callbackUrl\": \"https://example.com/webhooks/pay-in\",\n \"successRedirectUrl\": \"https://example.com/pay-in/success\",\n \"failureRedirectUrl\": \"https://example.com/pay-in/failure\",\n \"externalRef\": \"order-67890\",\n \"idempotencyKey\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inAmount\": \"100.00\",\n \"inCurrency\": \"EUR\",\n \"outCryptocurrency\": \"USDC\",\n \"callbackUrl\": \"https://example.com/webhooks/pay-in\",\n \"successRedirectUrl\": \"https://example.com/pay-in/success\",\n \"failureRedirectUrl\": \"https://example.com/pay-in/failure\",\n \"externalRef\": \"order-67890\",\n \"idempotencyKey\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": {
"id": "5e6f7081-92a3-4b4c-8d5e-6f708192a3b4",
"accountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
"status": "CREATED",
"inAmount": 100,
"inCurrency": "EUR",
"outCryptocurrency": "USDC",
"paymentUrl": "https://pay.example.com/session/5e6f708192a3b4c8",
"externalRef": "order-67890",
"walletId": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
"blockchainTxId": null,
"cancellable": true,
"expiresAt": "2026-01-15T10:30:00Z",
"metadata": {
"orderId": "67890"
},
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2026-01-15T09:30:00Z",
"updatedAt": "2026-01-15T09:30:00Z"
}
}{
"success": false,
"errors": [
{
"code": "no-suitable-provider",
"message": "No enabled pay-in provider supports EUR to USDC."
}
]
}{
"success": false,
"errors": [
{
"code": "unauthenticated",
"message": "Please authenticate to perform this action."
}
]
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": "kyc-required",
"message": "Account {accountId} KYC status is not verified"
}
]
}{
"success": false,
"errors": [
{
"code": "internal-error",
"message": "An unexpected error occurred. Please try again later."
}
]
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
],
"result": {}
}Requires scope:
manage:pay-in-sessions — see Required scopes.
Creates a hosted pay-in session. Redirect the payer to the returned paymentUrl; on completion the fiat is converted to the chosen cryptocurrency and credited to the account’s wallet. Provide a callbackUrl and a unique idempotencyKey (safe retries).
The account must be verified before a pay-in session can be created. See Account verification.
Errors
The codes this endpoint can return, in addition to the standard errors. Branch oncode, never the message.
| HTTP | code | When |
|---|---|---|
400 | no-suitable-provider | no enabled provider supports this currency combination |
400 | company-not-active | your company is not ACTIVE |
400 | account-not-active | the account is not ACTIVE |
400 | idempotency-key-conflict | the idempotencyKey is already used by a different account |
422 | kyc-required | the account’s KYC status is not VERIFIED |
422 | unsupported-asset | outCryptocurrency is not a supported asset for your company |
Authorizations
OAuth2 client credentials flow. Token endpoints:
Path Parameters
Unique account identifier
Body
application/json
Fiat amount to pay in
Pattern:
^\d+(\.\d{1,2})?$Fiat currency of the incoming payment (e.g. EUR)
Minimum string length:
1Cryptocurrency to convert the incoming fiat to (e.g. USDC)
Minimum string length:
1HTTPS URL to receive payment status callbacks
Pattern:
^https://.*Unique UUID key to prevent duplicate operations on retry
URL to redirect the user to on successful payment
URL to redirect the user to on failed payment
Optional external reference
Maximum string length:
255Show child attributes
Show child attributes
Was this page helpful?

