中文 ▾
RU EN 中文 TR ES PT

开发者

Host-to-Host 对接 —— 服务器与服务器直接通信。您通过 API 创建订单，获取收款信息并在自己的页面展示给付款人，无需跳转到 CrocoPay。

3 个接口 11 种货币 请求头认证 HMAC 签名回调

您通过 API 创建订单，获取收款信息（卡号、手机号或二维码）并在自己的页面展示给付款人 —— 无需跳转到 CrocoPay。

认证

所有请求都需要请求头 Client-Id 和 Client-Secret。密钥位于“商店”→ 商户旁的齿轮图标。

Client-Id: GnHqauRCUVtB8sECR7m
Client-Secret: vpBpXo7REyApkDnLIOpMR3lk1ndaLmY2qoZptV9cHOtjJLUDsW26GBSe2kda1IVQIMR758Z

1. 创建订单

POST /api/v2/h2h/invoices

创建新的支付订单，返回订单 ID 和收款信息。

amount 是 付款金额（独联体货币为整数）
currency 是 币种：RUB、UAH、UZS、KZT、TJS、AZN、KGS
payment_option 是 支付方式（TO_CARD、SBP、QR_NSPK…）
callback_url 否 付款 Webhook 通知地址（POST）
success_url 否 付款成功后付款人的跳转地址。不传时付款人将看到 CrocoPay 确认页面
cancel_url 否 付款人取消付款或订单过期时的跳转地址。不传时付款人停留在 CrocoPay 页面 
POST /api/v2/h2h/invoices HTTP/1.1
Host: crocopay.tech
Client-Id: GnHqauRCUVtB8sECR7m
Client-Secret: vpBpXo7REyApkDnLIOpMR3lk1ndaLmY2qoZptV9cHOtjJLUDsW26GBSe2kda1IVQIMR758Z
Content-Type: application/json

{
    "amount": 5000,
    "currency": "RUB",
    "payment_option": "TO_CARD",
    "callback_url": "https://example.com/payment?user_id=42",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
}
响应 —— 银行卡信息（TO_CARD）
HTTP/1.1 200 OK

{
    "id": "911c2823-f55b-43b5-9881-d5653107f7dc",
    "status": "Pending",
    "amount": 5000,
    "currency": "RUB",
    "payment_option": "TO_CARD",
    "card": "4276 1234 5678 9012",
    "bank_receiver": "Sberbank",
    "card_owner": "IVAN PETROV",
    "expires_at": "2026-09-15T12:30:00Z"
}
响应 —— 手机号信息（SBP / TRANSGRAN_SBER）
HTTP/1.1 200 OK

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "Pending",
    "amount": 5000,
    "currency": "RUB",
    "payment_option": "SBP",
    "card": "+79001234567",
    "bank_receiver": "Alfa-Bank",
    "card_owner": "ANNA SIDOROVA",
    "expires_at": "2026-09-15T12:30:00Z"
}
响应 —— 错误
HTTP/1.1 422 Unprocessable Entity

{
    "status": "error",
    "message": "payment_option TO_CARD is not enabled for currency UZS"
}

2. 查询订单

GET /api/v2/h2h/invoices/{id}

按 UUID 返回订单的当前状态和收款信息 —— 可用于轮询直到付款完成。

Pending
等待付款
Success
已付款
Expired
付款时间已过期
Cancelled
已取消
Failed
付款错误

3. 可用支付方式

GET /api/v2/h2h/payment-method/available

返回您商店可用的支付方式 —— 请在创建订单前调用。

HTTP/1.1 200 OK

{
    "methods": [
        { "currency": "RUB", "payment_option": "TO_CARD",       "name": "银行卡（任意俄罗斯银行）" },
        { "currency": "RUB", "payment_option": "SBP",            "name": "SBP（任意俄罗斯银行）" },
        { "currency": "RUB", "payment_option": "SBP_ALFA",       "name": "SBP Alfa-Bank" },
        { "currency": "RUB", "payment_option": "QR_NSPK",        "name": "NSPK 二维码" },
        { "currency": "RUB", "payment_option": "TRANSGRAN_SBER", "name": "跨境 · SberPay" },
        { "currency": "UAH", "payment_option": "TO_CARD",        "name": "银行卡（乌克兰）" },
        { "currency": "UZS", "payment_option": "TO_CARD",        "name": "银行卡（乌兹别克斯坦）" },
        { "currency": "TJS", "payment_option": "TO_CARD",        "name": "银行卡（塔吉克斯坦）" },
        { "currency": "AZN", "payment_option": "TO_CARD",        "name": "银行卡（阿塞拜疆）" },
        { "currency": "KZT", "payment_option": "TO_CARD",        "name": "银行卡（哈萨克斯坦）" },
        { "currency": "KGS", "payment_option": "TO_CARD",        "name": "银行卡（吉尔吉斯斯坦）" }
    ]
}

各币种的 payment_option

参数 payment_option 的取值取决于币种。请向客户经理确认您的商店已开通哪些方式。

RUB Russia
TO_CARD Bank card transfer (any Russian bank) Card number
SBP SBP transfer — any Russian bank Phone number
SBP_ALFA SBP transfer — Alfa-Bank Phone number
SBP_TBANK SBP transfer — T-Bank Phone number
QR_NSPK NSPK QR code payment QR code
MOBILE_PHONE Mobile phone top-up Phone number
TO_CARD_TRANSGRAN Cross-border card transfer (any bank) Card number
SBP_TRANSGRAN Cross-border SBP transfer (any bank) Phone number
TRANSGRAN_ALFA Cross-border — Alfa-Bank Card / phone
TRANSGRAN_VTB Cross-border — VTB Card / phone
TRANSGRAN_SBER Cross-border — SberPay Phone number
TRANSGRAN_TPAY Cross-border — T-Pay (T-Bank) Card / phone
UAH Ukraine
TO_CARD Bank card transfer (Ukraine) Card number
UZS Uzbekistan
UZCARD UzCard card transfer Card number
HUMO Humo card transfer Card number
PAYME Payme transfer Card / phone
CLICK Click transfer Card / phone
KZT Kazakhstan
BANK_TRANSFER Bank transfer (Kazakhstan) Card number
AZN Azerbaijan
BANK_TRANSFER Bank transfer (Azerbaijan) Card number
TJS Tajikistan
KORTI_MILLI Transfer — Korti Milli Card number
DUSHANBE_CITY Transfer — Dushanbe City Bank Card number
KGS Kyrgyzstan
TO_CARD Bank card transfer (Kyrgyzstan) Card number

付款人跳转

success_url
付款成功后，付款人会自动跳转到指定 URL。如未传该参数，付款人将看到 CrocoPay 付款确认页面。
cancel_url
如果付款人取消付款或订单过期，将跳转到此 URL。如未传，付款人停留在 CrocoPay 页面。
重要： 跳转到 success_url 并不代表已付款 —— 付款人可以篡改 URL。请仅通过 Webhook（callback_url）并校验 HMAC 签名来确认付款。

Webhook (Callback)

付款成功后，CrocoPay 会向您的以下地址发送 POST： callback_url.

POST /payment?user_id=42 HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "timestamp": 1753282096,
    "subtotal": 500000,
    "percentage": 0,
    "charge_percentage": 0,
    "charge_fixed": 0,
    "total": 500000,
    "sign": "ef5954715c663e3f96194a03981a0b04dd0772bfa5164afcdb507470c9c5078d"
}
签名校验（PHP）
$expected = hash_hmac('sha256',
    "{$_POST['timestamp']}|{$_POST['subtotal']}|{$_POST['percentage']}|" .
    "{$_POST['charge_percentage']}|{$_POST['charge_fixed']}|{$_POST['total']}",
    $yourClientSecret
);

if (!hash_equals($expected, $_POST['sign'])) {
    http_response_code(403);
    exit('Invalid signature');
}
// 付款已确认
需要 API 密钥？
注册 —— Client-Id 和 Client-Secret 在“商店”中发放。
注册