결제 요청 API

인증

결제 요청 → API 및 webhook에서 키를 만드세요(계정에 2단계 인증이 켜져 있어야 합니다). Authorization 헤더로 보내고 서버에만 보관하세요. 권한을 선택하세요: “결제 요청 조회 및 생성”(매장) 또는 “조회 전용”(대사, 보고서). 조회 전용 키로 생성을 시도하면 403을 받습니다.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

결제 요청 생성

token: USDC 또는 SOL. valor: 점을 쓰는 소수, 또는 금액 미지정이면 생략. validade_horas: 1, 24, 72, 168 또는 720(기본값 24). externo_id: 매장의 주문 번호로, 계정당 고유해야 합니다. 네트워크가 끊겨도 안전하게 재시도할 수 있도록 Idempotency-Key(UUID)를 보내세요.

curl -X POST https://ducripto.com/api/v1/cobrancas \
  -H "Authorization: Bearer ib_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a8e-4b1d-4c55-9a3e-0d2b7f9e1c11" \
  -d '{"token":"USDC","valor":"25.90","descricao":"Pedido 1042","externo_id":"1042","validade_horas":24}'

{
  "id": "9b2f…", "estado": "pendente", "externo_id": "1042",
  "token": "USDC", "decimais": 6, "valor_unidades": "25900000", "valor": "25.9",
  "url_pagamento": "https://ducripto.com/pagar/9b2f…",
  "solana_pay": "solana:<carteira>?amount=25.9&spl-token=EPjF…&reference=…",
  "expira_em": "…", "pagamento": null
}

조회

금액은 항상 정밀도 손실 없이 토큰의 정수 단위 텍스트(valor_unidades)로 반환됩니다. estado: pendente, paga, expirada 또는 cancelada. 목록은 페이지 단위로 제공됩니다. limite(1~100, 기본값 50)를 사용하고 다음 페이지를 읽으려면 proximo 값을 depois에 넣으세요. proximo가 null이면 끝입니다. 서버에서 거래를 구성하는 지갑(Solana Pay "transaction request")에는 solana_pay_transacao를 사용하세요. 금액 미지정 결제 요청에서는 인코딩 전에 URL에 ?quantidade=를 추가하세요.

curl https://ducripto.com/api/v1/cobrancas/9b2f… -H "Authorization: Bearer ib_…"
curl "https://ducripto.com/api/v1/cobrancas?externo_id=1042" -H "Authorization: Bearer ib_…"
curl "https://ducripto.com/api/v1/cobrancas?limite=50&depois=<proximo>" -H "Authorization: Bearer ib_…"

Webhook: 결제 완료

tipo가 cobranca.paga인 JSON POST를 받습니다. 서명을 확인하세요: 비밀 값으로 "timestamp.body"를 HMAC-SHA256한 hex 값이며, timestamp가 5분보다 오래되었으면 거부하세요. 2xx로 응답하세요. 그렇지 않으면 점점 간격을 늘려 재전송합니다. 중복을 무시하려면 evento_id를 사용하세요.

import { createHmac, timingSafeEqual } from 'node:crypto';

// corpo = texto CRU da requisição (antes de JSON.parse)
// x-interbank-assinatura-anterior só vem durante uma troca de chaves da plataforma: aceite qualquer uma
export function webhookValido(corpo, cab, segredo) {
  const ts = cab['x-interbank-timestamp'];
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperado = createHmac('sha256', segredo).update(`${ts}.${corpo}`).digest();
  return ['x-interbank-assinatura', 'x-interbank-assinatura-anterior'].some((h) => {
    const veio = Buffer.from(cab[h] ?? '', 'hex');
    return veio.length === esperado.length && timingSafeEqual(veio, esperado);
  });
}

웹사이트 결제 버튼(SDK)

스크립트 한 줄로 귀사 브랜드의 버튼을 그리고 새 탭에서 결제 화면을 엽니다. 결제가 확인되면 웹사이트가 checkout:paga 이벤트를 받습니다. 이 이벤트는 화면 표시용입니다. 서버에서 확인(서명된 webhook 또는 결제 요청 GET)한 후에 주문을 처리하세요.

<!-- data-cobranca: id devolvido por POST /api/v1/cobrancas · data-voltar: opcional, só do seu site -->
<script src="https://ducripto.com/sdk/v1/checkout.js" data-cobranca="9b2f…" data-voltar="/obrigado" async></script>
<script>
  addEventListener('checkout:paga', (e) => mostrarObrigado(e.detail.cobranca));
</script>

어떤 토큰이든 USDC로 받기

금액이 있는 USDC 결제 요청을 만들 때 "aceita_conversao": true를 보내세요. 결제 페이지에서 지불자는 SOL, USDT, JUP 또는 BONK를 선택하고 지출 금액을 확인하며, 하나의 거래로 환전되어 정확한 USDC 금액이 귀사 지갑으로 전달됩니다. webhook과 조회는 동일합니다. 기준은 도착한 USDC입니다. 테스트 모드에서는 적용되지 않습니다.

curl -X POST https://ducripto.com/api/v1/cobrancas -H "Authorization: Bearer ib_…" -H "Content-Type: application/json" \
  -d '{"token":"USDC","valor":"49.90","externo_id":"1043","aceita_conversao":true}'
# → { "aceita_conversao": true, "url_pagamento": "https://ducripto.com/pagar/…", … }
# quem paga escolhe SOL, USDT, JUP ou BONK na página; você recebe 49.90 USDC exatos

테스트 환경(sandbox)

테스트 모드로 키를 만드세요(ib_test_로 시작). 같은 API를 사용하지만 테스트 결제 요청만 보고 만들 수 있으며, 이는 테스트 네트워크에 남고(응답과 webhook에 modo: "teste") 실제 잔액에는 절대 들어가지 않습니다. 지갑 없이 테스트하려면 결제를 시뮬레이션하세요: POST /api/v1/cobrancas/{id}/simular-pagamento (금액 미지정이면 {"valor": "…"}를 보내세요). cobranca.paga webhook은 실제와 똑같이 서명되어 도착합니다. 운영 키는 시뮬레이션할 수 없으며, 한 키는 다른 키의 결제 요청을 볼 수 없습니다.

# chave de teste (ib_test_…): mesma API, só cobranças de teste, rede de testes
curl -X POST https://ducripto.com/api/v1/cobrancas -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" -d '{"token":"USDC","valor":"25.90","externo_id":"teste-1"}'
# → { "id": "9b2f…", "modo": "teste", "rede": "devnet", "estado": "pendente", … }

curl -X POST https://ducripto.com/api/v1/cobrancas/9b2f…/simular-pagamento -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…"
# → { "estado": "paga", "pagamento": { "assinatura": "simulado_…", … } } e o webhook cobranca.paga com "modo": "teste"

오류와 한도

오류는 { erro: { codigo, mensagem } } 형식으로 반환됩니다. 401 잘못되었거나 폐기된 키 · 403 키에 해당 작업 권한 없음 · 404 다른 계정의 결제 요청이거나 존재하지 않음 · 409 externo_id 중복 또는 다른 본문으로 Idempotency-Key 재사용 · 422 잘못된 데이터 · 429 키당 분당 120회 초과.

계약(OpenAPI)

결제 요청, 오류, webhook을 포함한 전체 OpenAPI 3.1 명세는 /api/v1/openapi.json에 있습니다. Postman, Insomnia 또는 클라이언트 생성기로 가져오세요. 테스트가 실제 응답과 대조하는 것과 같은 스키마에서 생성됩니다.

curl https://ducripto.com/api/v1/openapi.json