Developers

주문 및 멱등성

주문 생성은 요율을 고정하고 입금 주소를 할당합니다. 통합 실수가 자금을 이동시키는 유일한 지점입니다. 멱등성은 그곳에서 편의가 아닙니다.

게시된 계약, 아직 공개되지 않음

이 엔드포인트는 현재 노출되지 않습니다. 사전에 통합을 구축할 수 있도록 문서화되어 있습니다. 그 형태는 확정되었으며, 주요 변경 사항은 새 버전과 변경 로그 항목을 통해 진행됩니다.

POST/api/v1/ordersPublished contract, not open

주문 생성

환율을 고정하고 전용 입금 주소를 반환합니다. 주문은 고정된 내역을 포함합니다: 재생 가능하므로 몇 달 후에도 적용된 정확한 가격을 재구성할 수 있습니다. Idempotency-Key 헤더가 필요합니다.

인증: Authorization: Bearer … 인증 보기

매개변수

매개변수
필드	유형	설명
`quoteId`필수	string	수락된 견적의 식별자.
`beneficiary`필수	object	레일 스키마에 의해 부과되는 필드. 이름은 확인된 신원과 일치해야 합니다: 제3자 지급은 허용되지 않습니다.
`networkId`필수	string	입금이 전송될 네트워크. 반환되는 주소와 일부 네트워크에서는 필수 메모를 결정합니다.

요청bash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

응답 — 게시된 계약json

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

메모는 대부분의 네트워크에서 null이며 XRP, Stellar 및 TON에서는 필수입니다. 이를 생략하면 자금이 손실됩니다: null이 아닌 즉시 필드를 필수로 취급하십시오.

가능한 오류: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. 전체 카탈로그

GET/api/v1/orders/{reference}Published contract, not open

주문 조회

현재 상태 및 타임스탬프가 있는 전환 기록. 기록은 진실의 원천입니다: 추가 전용이며 다시 쓰이지 않으며 "내 주문이 왜 그 시점에 그 상태로 이동했는지"에 대한 답변입니다.

인증: Authorization: Bearer … 인증 보기

요청bash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

응답 — 게시된 계약json

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

가능한 오류: unauthorized, not_found. 전체 카탈로그

멱등성

네트워크에서 시간 초과된 생성 요청은 주문이 생성되었는지 여부를 알려주지 않습니다. 멱등성 키 없이는 두 가지 나쁜 선택만 있습니다: 재시도하여 두 주문의 위험을 감수하거나, 재시도하지 않아 주문이 없을 위험을 감수하는 것입니다.

헤더http

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

의도당 하나의 키

키는 HTTP 요청이 아닌 '해당 주문 생성' 의도를 식별합니다. 귀하 측의 고유 ID: 장바구니 ID, 호출 전에 생성된 UUID, 절대 카운터가 아닙니다.

재생은 원래 응답을 반환합니다

동일한 키와 동일한 본문으로 재생하면 첫 번째 요청의 응답이 동일한 HTTP 상태로 반환됩니다. 이것이 시간 초과 후에도 재시도를 안전하게 만드는 이유입니다.

동일한 키, 다른 본문: 충돌

응답은 명시적 충돌입니다. 내용이 변경되면 키도 변경되어야 합니다. 그렇지 않으면 두 주문 중 어느 것을 재생할지 알 수 없습니다.

24시간 보존

그 후 키는 잊혀지고 재생은 새 주문을 생성합니다. 창 내에서 재시도하거나 읽기 엔드포인트로 상태를 확인하십시오.

메모, 필요한 네트워크에서

XRP, Stellar 및 TON에서는 입금 주소만으로는 충분하지 않습니다. 추가 식별자가 최종 수취인을 지정합니다. 이는 오프램프 통합에서 가장 비용이 많이 드는 사고 원인입니다.

메모 없는 입금은 분실 입금입니다

메모 필드는 대부분의 네트워크에서 null이며, 이를 요구하는 네트워크에서는 null이 아닙니다. null이 아닌 즉시 필수로 취급하고 주소와 동일한 중요도로 표시하십시오. 공유 주소에 메모 없이 도착한 입금은 수동 복구가 필요하며 항상 성공하지는 않습니다.

주문 상태

아래 상태는 통합에서 관찰할 수 있는 상태입니다. 전환은 타임스탬프가 찍혀 추가되며 다시 작성되지 않습니다. 기록은 '내 주문이 그 시점에 그 상태로 이동한 이유'에 답합니다.

주문 상태
상태	의미
`QUOTE_LOCKED`	요율이 고정되었습니다. 주문은 수취인 세부 정보 또는 신원 확인을 기다립니다.
`AWAITING_DEPOSIT`	입금 주소가 할당되었고 입금 창이 실행 중입니다. 자금을 보낼 수 있는 유일한 순간입니다.
`DEPOSIT_DETECTED`	네트워크에서 수신 거래가 확인되었지만 아직 확인되지 않았습니다. 사용자를 안심시키고 아무것도 전달하지 마십시오.
`CONFIRMING`	확인이 누적되고 있습니다. 필요한 수는 금액이 아닌 네트워크에 따라 다릅니다.
`DEPOSIT_CONFIRMED`	입금이 안전하게 확보되었습니다. 규정 준수 및 재가격 규칙이 여기서 평가됩니다.
`UNDERPAID`	수신 금액이 허용 오차 이상으로 예상보다 낮습니다. 세 가지 결과: 추가 입금, 수신 금액으로 계속 또는 환불.
`OVERPAID`	수신 금액이 예상 금액을 초과합니다. 초기 금액은 고정된 환율로 유지되며, 초과분은 별도로 처리됩니다.
`PAYOUT_QUEUED`	송금이 대기열에 있습니다. 대기열은 여러 작업자가 동시에 실행되더라도 지급이 한 번만 전송되도록 보장합니다.
`PAYOUT_SENT`	송금이 지급 경로를 통해 발송되었습니다. 발송은 수신을 의미하지 않습니다. 최종 지연은 수취인의 은행에 따라 달라집니다.
`COMPLETED`	지급 경로를 통해 결제가 확인되었습니다. 최종 상태입니다.
`PAYOUT_FAILED`	지급 경로가 송금을 거부하거나 반환했습니다. 자동 재시도는 없습니다. 원인은 거의 항상 세부 정보에 있습니다.
`REFUNDED`	자금이 네트워크 수수료를 차감한 후 원래 주소로 반환되었습니다. 최종 상태입니다.