Payment API

Payment API를 사용하면 결제 세션을 생성하고, 고객을 호스팅된 결제 페이지로 리디렉션하며, 결제 상태를 추적할 수 있습니다.

결제 생성

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

호스티드 체크아웃, H2H, 그리고 정확한 암호화폐 금액

동일한 엔드포인트가 세 가지 별개의 인보이스 형식을 지원합니다. 하나를 신중하게 선택하고 금액 의미를 섞지 마십시오.

결제자 선택이 가능한 호스티드 체크아웃

amount, currency, order_id, 그리고 url_callback를 보내고 to_currency와 network는 생략하십시오. 응답에는 result.url가 포함되며, address, qr, 그리고 때로는 결제자 필드는 결제자가 호스티드 페이지에서 방향을 선택할 때까지 null로 남아 있습니다.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

직접 주소 H2H 인보이스

to_currency와 network를 모두 전송하세요. 2328.io는 API 호출 중에 블록체인 인보이스를 생성하므로, 고객을 리디렉션하지 않고도 체크아웃 내에서 성공적인 응답을 렌더링할 수 있습니다.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

반환된 값 그대로 렌더링하세요:

• payer_amount와 payer_currency — 결제 지침;
• network와 address — 이 인보이스의 유일한 목적지;
• qr — 동일한 주소에 대한 데이터 URI;
• expires_at — 인보이스 마감 기한;
• url — 커스텀 체크아웃이 완료되지 못할 때 유용한 호스팅된 대체 방법.

정확한 암호화폐 금액에 대한 송장

송장 자체가 암호화폐로 표시될 때 암호화폐를 currency에 넣으십시오:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

요청한 암호화폐 값은 payer_currency / payer_amount에 보존됩니다. 서비스는 회계 및 환율 필드를 위해 내부적으로 USD 평가액도 유지할 수 있습니다; 정확한 암호화폐 지침을 해당 평가액으로 대체하지 마십시오. 반환된 소수 문자열을 후행 소수점 자리까지 포함하여 보존하십시오.

네트워크가 하나만 지원되는 암호화폐의 경우, 네트워크는 자동으로 선택될 수 있습니다. 결정적 통합을 위해 network를 명시적으로 제공하는 것이 여전히 권장됩니다. 스테이블코인과 같은 다중 네트워크 자산의 경우, 항상 이를 전송하세요.

멱등성과 재시도

order_id는 인증된 상인 프로젝트에 범위가 지정되며 생성 멱등성 키로 작용합니다. 결제가 이미 존재하면 API는 state: 0와 함께 해당 세션을 반환합니다.

추천 생성 알고리즘:

1. 로컬 결제 시도와 고유 order_id를 하나의 데이터베이스 트랜잭션에 삽입합니다.
2. 서명된 API 요청을 보냅니다.
3. 반환된 uuid 및 전체 응답을 저장합니다.
4. HTTP 결과가 손실된 경우, 동일한 요청을 재시도하거나 order_id로 /v1/payment/info를 조회합니다.
5. 상류 요청이 시간 초과되었다고 해서 두 번째 로컬 주문을 생성하지 마십시오.

결제 엣지 케이스

브라우저 반환 URL은 탐색 전용입니다. 고객은 결제하지 않고 열거나, 결제 후 닫거나, 나중에 다시 재생할 수 있습니다. 상인 주문을 완료할 수 있는 것은 검증된 API/웹훅 상태뿐입니다.

결제 정보

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

결제 목록

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"