PT ▾
RU EN 中文 TR ES PT

Desenvolvedores

Integração Host-to-Host — comunicação direta de servidor para servidor. Você cria uma fatura pela API, recebe os dados de pagamento e os mostra ao pagador no seu site, sem redirecionar para a CrocoPay.

3 endpoints 11 moedas Autenticação por cabeçalhos Callback assinado com HMAC

Você cria uma fatura pela API, recebe os dados de pagamento (cartão, telefone ou QR) e os mostra ao pagador no seu site — sem redirecionar para a CrocoPay.

Autenticação

Todas as requisições exigem os cabeçalhos Client-Id e Client-Secret. As chaves ficam em «Lojas» → ícone de engrenagem ao lado do lojista.

Client-Id: GnHqauRCUVtB8sECR7m
Client-Secret: vpBpXo7REyApkDnLIOpMR3lk1ndaLmY2qoZptV9cHOtjJLUDsW26GBSe2kda1IVQIMR758Z

1. Criar uma fatura

POST /api/v2/h2h/invoices

Cria uma nova fatura de pagamento. Retorna o ID da fatura e os dados de pagamento.

amount sim Valor do pagamento (inteiro para moedas da CEI)
currency sim Moeda: RUB, UAH, UZS, KZT, TJS, AZN, KGS
payment_option sim Método de pagamento (TO_CARD, SBP, QR_NSPK…)
callback_url não URL para a notificação webhook do pagamento (POST)
success_url não Para onde redirecionar o pagador após um pagamento bem-sucedido. Se omitido, o pagador verá uma página de confirmação da CrocoPay
cancel_url não Para onde redirecionar o pagador se ele cancelar ou a fatura expirar. Se omitido, o pagador fica na página da 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"
}
Resposta — dados do cartão (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"
}
Resposta — dados do telefone (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"
}
Resposta — erro
HTTP/1.1 422 Unprocessable Entity

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

2. Consultar uma fatura

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

Retorna o status atual e os dados de pagamento de uma fatura pelo UUID — use para consultar até o pagamento.

Pending
Aguardando pagamento
Success
Pago
Expired
Prazo de pagamento expirado
Cancelled
Cancelado
Failed
Erro de pagamento

3. Métodos de pagamento disponíveis

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

Retorna os métodos de pagamento disponíveis para sua loja — chame antes de criar uma fatura.

HTTP/1.1 200 OK

{
    "methods": [
        { "currency": "RUB", "payment_option": "TO_CARD",       "name": "Cartão (qualquer banco russo)" },
        { "currency": "RUB", "payment_option": "SBP",            "name": "SBP (qualquer banco russo)" },
        { "currency": "RUB", "payment_option": "SBP_ALFA",       "name": "SBP Alfa-Bank" },
        { "currency": "RUB", "payment_option": "QR_NSPK",        "name": "QR NSPK" },
        { "currency": "RUB", "payment_option": "TRANSGRAN_SBER", "name": "Transfronteiriço · SberPay" },
        { "currency": "UAH", "payment_option": "TO_CARD",        "name": "Cartão (Ucrânia)" },
        { "currency": "UZS", "payment_option": "TO_CARD",        "name": "Cartão (Uzbequistão)" },
        { "currency": "TJS", "payment_option": "TO_CARD",        "name": "Cartão (Tajiquistão)" },
        { "currency": "AZN", "payment_option": "TO_CARD",        "name": "Cartão (Azerbaijão)" },
        { "currency": "KZT", "payment_option": "TO_CARD",        "name": "Cartão (Cazaquistão)" },
        { "currency": "KGS", "payment_option": "TO_CARD",        "name": "Cartão (Quirguistão)" }
    ]
}

payment_option por moeda

O valor de payment_option depende da moeda. Pergunte ao seu gerente quais métodos estão ativados para sua loja.

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

Redirecionamento do pagador

success_url
Após um pagamento bem-sucedido, o pagador é redirecionado automaticamente para a URL informada. Se o parâmetro não for enviado, o pagador verá a página de confirmação de pagamento da CrocoPay.
cancel_url
Se o pagador cancelar ou a fatura expirar, ele é redirecionado para esta URL. Se não for enviado, o pagador fica na página da CrocoPay.
Importante: o redirecionamento para success_url não confirma o pagamento — o pagador pode alterar a URL. Confirme o pagamento somente pelo webhook (callback_url) com verificação da assinatura HMAC.

Webhook (Callback)

Após um pagamento bem-sucedido, a CrocoPay envia um POST para o seu 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"
}
Verificação de assinatura (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');
}
// pagamento confirmado
Precisa de chaves de API?
Cadastre-se — seu Client-Id e Client-Secret são emitidos em «Lojas».
Cadastrar-se