创建入金订单

POST

order

fiat_to_crypto

创建入金订单

curl --request POST \
  --url https://api-test.velafi.com/v2/order/fiat_to_crypto \
  --header 'Content-Type: application/json' \
  --header 'X-BH-TOKEN: <api-key>' \
  --data '
{
  "country": "<string>",
  "crypto": "<string>",
  "fiat": "<string>",
  "paymentId": 123,
  "clientId": "<string>",
  "merchantId": 123,
  "fiatAmount": 123,
  "cryptoAmount": 123,
  "remark": "<string>",
  "depositAlias": "<string>",
  "quoteId": "<string>",
  "inFieldJson": {
    "inFieldJson.bank": "<string>"
  }
}
'

import requests

url = "https://api-test.velafi.com/v2/order/fiat_to_crypto"

payload = {
    "country": "<string>",
    "crypto": "<string>",
    "fiat": "<string>",
    "paymentId": 123,
    "clientId": "<string>",
    "merchantId": 123,
    "fiatAmount": 123,
    "cryptoAmount": 123,
    "remark": "<string>",
    "depositAlias": "<string>",
    "quoteId": "<string>",
    "inFieldJson": { "inFieldJson.bank": "<string>" }
}
headers = {
    "X-BH-TOKEN": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    country: '<string>',
    crypto: '<string>',
    fiat: '<string>',
    paymentId: 123,
    clientId: '<string>',
    merchantId: 123,
    fiatAmount: 123,
    cryptoAmount: 123,
    remark: '<string>',
    depositAlias: '<string>',
    quoteId: '<string>',
    inFieldJson: {'inFieldJson.bank': '<string>'}
  })
};

fetch('https://api-test.velafi.com/v2/order/fiat_to_crypto', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/order/fiat_to_crypto")
  .header("X-BH-TOKEN", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"<string>\",\n  \"crypto\": \"<string>\",\n  \"fiat\": \"<string>\",\n  \"paymentId\": 123,\n  \"clientId\": \"<string>\",\n  \"merchantId\": 123,\n  \"fiatAmount\": 123,\n  \"cryptoAmount\": 123,\n  \"remark\": \"<string>\",\n  \"depositAlias\": \"<string>\",\n  \"quoteId\": \"<string>\",\n  \"inFieldJson\": {\n    \"inFieldJson.bank\": \"<string>\"\n  }\n}")
  .asString();

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "data.orderId": 123
  }
}

法币兑加密货币入金 (On-Ramp) 会为您的用户将本地法币兑换为加密货币。请指定源法币、目标加密货币，并通过 paymentId 指定支付方式。订单金额可以用法币（fiatAmount）或加密货币（cryptoAmount）确定；如果同时传入两者，则以 fiatAmount 为准。如需锁定汇率，请传入通过报价 API 获取的 quoteId；若未传入，订单将按创建时的当前汇率定价。响应会返回一个 orderId，您可以通过获取订单和订单列表端点，使用它在订单整个生命周期内进行跟踪。

端点

POST https://api.velafi.com/v2/order/fiat_to_crypto

沙盒环境测试请使用 https://api-test.velafi.com/v2/order/fiat_to_crypto。

请求头

请求头	值
`X-BH-TOKEN`	通过 `GET /v2/token/generate` 获取的令牌
`Content-Type`	`application/json`

请求体参数

string

必填

入金所在国家的完整名称（例如 "Mexico"、"Brazil"）。必须与所选 paymentId 支持的国家一致。

string

必填

目标加密货币的代码（例如 "USDT"、"USDC"、"BTC"）。

string

必填

用户付款所用法币的 ISO 4217 代码（例如 "MXN"、"BRL"、"COP"）。

integer

必填

法币充值所用支付方式的数字 ID。请参阅支付模板参考中的支付方式 ID 表。

string

您自己的订单参考 ID，最多 40 个字符。它在您账户下所有 fiat_to_crypto 和 crypto_to_fiat 订单中必须唯一；使用相同 clientId 的第二次创建请求将被拒绝。该字段会在获取订单的响应中返回，并可代替 orderId 用于查询订单。请参阅幂等性与重试。

integer

必填

订单所属商户的数字 ID。未提供有效 merchantId 的请求将被拒绝。

decimal

用户支付的法币金额（例如 1000.00）。请提供 fiatAmount 或 cryptoAmount；如果同时传入两者，则以 fiatAmount 为准。

decimal

用户收到的加密货币数量（例如 46.73）。如果同时传入了正数的 fiatAmount，则忽略此字段。

string

附加到订单的可选自由文本备注。

string

用于法币充值的虚拟账户别名。基于虚拟账户的支付方式必须提供。

string

通过报价 API 获取的报价 ID，用于锁定特定汇率。省略则使用实时现货汇率。

object

某些支付方式所需的额外支付专用字段。

显示 inFieldJson 字段

string

付款人银行代码，当 paymentId 为 141（PSE）时必填。PSE 使用其独立的银行列表，与收款人所用的哥伦比亚银行代码表不同。

显示 PSE 银行代码

代码	银行
1001	BANCO DE BOGOTA
1002	BANCO POPULAR
1006	ITAU
1007	BANCOLOMBIA
1009	CITIBANK
1012	BANCO GNB SUDAMERIS
1013	BBVA COLOMBIA
1019	DAVIBANK
1023	BANCO DE OCCIDENTE
1032	BANCO CAJA SOCIAL BCSC SA
1040	BANCO AGRARIO
1047	BANCO MUNDO MUJER
1051	BANCO DAVIVIENDA SA
1052	BANCO AV VILLAS
1059	BANCO DE LAS MICROFINANZAS - BANCAMIA S.A.
1060	BANCO PICHINCHA
1061	BANCOOMEVA
1062	BANCO FALABELLA S.A.
1063	BANCO FINANDINA S.A.
1065	BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A
1066	BANCO COOPERATIVO COOPCENTRAL
1069	BANCO SERFINANZA S.A
1070	LULO BANK S.A.
1071	BANCO J.P. MORGAN COLOMBIA S.A.
1097	Dale
1121	FINANCIERA JURISCOOP S.A. COMPAÑIA DE FINANCIAMIENTO
1283	COOPERATIVA FINANCIERA DE ANTIOQUIA
1286	JFK COOPERATIVA FINANCIERA
1289	COOTRAFA COOPERATIVA FINANCIERA
1292	CONFIAR COOPERATIVA FINANCIERA
1303	BANCO UNION S.A
1370	COLTEFINANCIERA S.A
1507	NEQUI
1551	DAVIPLATA
1558	BAN100 S.A
1637	IRIS
1801	MOVII
1802	DING TECNIPAGOS SA
1804	UALA
1808	BOLD CF
1809	NU COLOMBIA
1811	RAPPIPAY
1812	COINK
1814	GLOBAL66
1815	Alianza fiduciaria
1816	Crezcamos

响应字段

integer

响应状态码。200 表示成功。

string

可读的响应消息。

object

订单结果对象。

显示 data 字段

integer

所创建订单的唯一数字 ID。可用于查询订单状态和详情。

示例

curl -X POST "https://api.velafi.com/v2/order/fiat_to_crypto" \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "Colombia",
    "clientId": "my-order-2024-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "COP",
    "fiatAmount": 100000.00,
    "paymentId": 141,
    "remark": "On-ramp for user #42",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "inFieldJson": {
      "bank": "1001"
    }
  }'

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": 1123123123
  }
}

创建订单后，轮询 GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_crypto 以监控其状态。新订单的初始状态为 status: 40（待付款）；如果需要合规审核或补充材料，则为 10、11 或 31。使用自动支付方式的订单会通过 VelaFi 的银行集成进入 status: 50（已付款）。对于手动支付方式，请在转账发出后调用 POST /v2/order/confirm 将订单标记为已付款。

幂等性与重试

使用 clientId 可让订单创建请求安全地重试。

clientId 为可选字段。传入时，其长度不得超过 40 个字符，并且在您账户下所有商户的全部 fiat_to_crypto 和 crypto_to_fiat 订单中必须唯一。
重复使用已有 clientId 的创建请求会因重复提交错误而被拒绝，且不会创建新订单。响应不会返回原订单，请改为查询该订单。
clientId 会永久绑定到其订单，即使订单被取消后也是如此。新订单请使用新的 clientId。
通过 GET /v2/order/detail?orderType=fiat_to_crypto&clientId={clientId} 按 clientId 查询订单。

如果创建请求超时或未返回响应：

使用相同的 orderType 和 clientId 调用 GET /v2/order/detail。
如果找到该订单，说明原始请求已成功。请勿再次创建。
如果未找到，请使用相同的 clientId 重试。如果第一次请求在此期间确实已创建订单，重试将作为重复请求被拒绝，而不会创建第二个订单。

quoteId 可能会被一个随后被拒绝的创建请求消耗掉。重试前请重新请求报价。

⌘I

创建入金订单

curl --request POST \
  --url https://api-test.velafi.com/v2/order/fiat_to_crypto \
  --header 'Content-Type: application/json' \
  --header 'X-BH-TOKEN: <api-key>' \
  --data '
{
  "country": "<string>",
  "crypto": "<string>",
  "fiat": "<string>",
  "paymentId": 123,
  "clientId": "<string>",
  "merchantId": 123,
  "fiatAmount": 123,
  "cryptoAmount": 123,
  "remark": "<string>",
  "depositAlias": "<string>",
  "quoteId": "<string>",
  "inFieldJson": {
    "inFieldJson.bank": "<string>"
  }
}
'

import requests

url = "https://api-test.velafi.com/v2/order/fiat_to_crypto"

payload = {
    "country": "<string>",
    "crypto": "<string>",
    "fiat": "<string>",
    "paymentId": 123,
    "clientId": "<string>",
    "merchantId": 123,
    "fiatAmount": 123,
    "cryptoAmount": 123,
    "remark": "<string>",
    "depositAlias": "<string>",
    "quoteId": "<string>",
    "inFieldJson": { "inFieldJson.bank": "<string>" }
}
headers = {
    "X-BH-TOKEN": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    country: '<string>',
    crypto: '<string>',
    fiat: '<string>',
    paymentId: 123,
    clientId: '<string>',
    merchantId: 123,
    fiatAmount: 123,
    cryptoAmount: 123,
    remark: '<string>',
    depositAlias: '<string>',
    quoteId: '<string>',
    inFieldJson: {'inFieldJson.bank': '<string>'}
  })
};

fetch('https://api-test.velafi.com/v2/order/fiat_to_crypto', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/order/fiat_to_crypto")
  .header("X-BH-TOKEN", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country\": \"<string>\",\n  \"crypto\": \"<string>\",\n  \"fiat\": \"<string>\",\n  \"paymentId\": 123,\n  \"clientId\": \"<string>\",\n  \"merchantId\": 123,\n  \"fiatAmount\": 123,\n  \"cryptoAmount\": 123,\n  \"remark\": \"<string>\",\n  \"depositAlias\": \"<string>\",\n  \"quoteId\": \"<string>\",\n  \"inFieldJson\": {\n    \"inFieldJson.bank\": \"<string>\"\n  }\n}")
  .asString();

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "data.orderId": 123
  }
}

概览

账户

配置

商户

加密钱包

收款人

报价

订单

Webhooks

创建入金订单

端点

请求头

请求体参数

响应字段

示例

幂等性与重试

​端点

​请求头

​请求体参数

​响应字段

​示例

​幂等性与重试

端点

请求头

请求体参数

响应字段

示例

幂等性与重试