팀이 정말로 즐겁게 쓸 수 있는 API
예측 가능한 REST, 멱등성 키, 서명된 웹훅, 시뮬레이션 레일을 갖춘 샌드박스로 실제 자금을 단 1프랑도 옮기기 전에 처음부터 끝까지 연동할 수 있습니다.
단 한 번의 요청으로 첫 수납
깔끔한 REST, 예측 가능한 JSON 응답 구조, 모든 응답에 포함되는 요청 ID. 샌드박스는 프로덕션과 동일합니다: 같은 API, 같은 상태값, 같은 웹훅.
- 앱별로 범위가 지정되는 샌드박스 및 프로덕션 키
- 재전송 공격 방지를 갖춘 HMAC 서명 웹훅
- 모든 자금 이동 호출에 적용되는 멱등성 키
- 무엇을 고쳐야 할지 정확히 알려주는 타입 지정 오류
- OpenAPI 명세, Postman 컬렉션, llms.txt 모두 공개
- CRM, ERP 및 쇼핑몰 커넥터를 위한 호스팅 결제 세션과 플랫 콜백
curl https://api.capayglobal.com/v1/collections \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 9f1c-collect-01" \
-H "Content-Type: application/json" \
-d '{
"amount": "2500",
"currency": "XAF",
"country": "CM",
"method": "mobile_money",
"msisdn": "2376XXXXXXXX",
"merchant_reference": "order-1042"
}'{
"status": "success",
"data": {
"id": "col_9xKQ2mD41Vb8",
"object": "collection",
"status": "pending",
"amount": "2500",
"currency": "XAF",
"country": "CM",
"method": "mobile_money",
"merchant_reference": "order-1042",
"fees": {
"platform_fee": "50",
"provider_fee": "0",
"total_fee": "50",
"bearer": "merchant"
},
"net_amount": null,
"livemode": false,
"created_at": "2026-08-30T12:04:11Z"
},
"request_id": "req_b0f3d2c1"
}첫 수납
요청 한 번으로 결제 인텐트를 만들고 요청 id를 돌려주며, 모바일 머니에서는 결제자 휴대폰으로 승인 요청을 보냅니다. 샌드박스는 프로덕션과 동일하게 동작합니다.
curl -X POST https://api.capayglobal.com/v1/collections \
-H "Authorization: Bearer sk_test_XXXXXXXXXXXX" \
-H "Idempotency-Key: col-order-10482-a1b2c3" \
-H "Content-Type: application/json" \
-d '{
"amount": "5000",
"currency": "XAF",
"country": "CM",
"method": "mobile_money",
"msisdn": "+237650000001",
"merchant_reference": "order-10482"
}'{
"status": "success",
"data": {
"id": "col_7Qm3k1Xa9Zr4",
"object": "collection",
"status": "pending",
"amount": "5000",
"currency": "XAF",
"auth_model": "STK_PROMPT",
"livemode": false
},
"request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}서버 SDK
같은 REST API 위의 얇고 타입이 있는 래퍼이며 멱등성과 서명 검증이 내장되어 있습니다.
import { Capay } from '@capay/sdk';아직 npm에 없습니다. 위의 임포트 줄은 확정본이므로, 공개된 뒤에도 연동을 바꿀 필요가 없습니다.
가이드 보기from capay import Capay아직 PyPI에 없습니다. 위의 임포트 줄은 확정본이므로, 공개된 뒤에도 연동을 바꿀 필요가 없습니다.
가이드 보기use Capay\CapayClient;아직 Packagist에 없습니다. 위의 임포트 줄은 확정본이므로, 공개된 뒤에도 연동을 바꿀 필요가 없습니다.
가이드 보기모든 webhook 검증
서명은 원본 본문으로 계산하고 상수 시간으로 비교하며, 300초보다 오래된 타임스탬프는 거부합니다. 검증하지 않은 webhook은 절대 신뢰하지 마세요.
# T is the t= value from X-Capay-Signature; delivery.json is the raw body as received.
T=1767225600
SECRET=whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
{ printf '%s.' "$T"; cat delivery.json; } \
| openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1
# Compare the printed hex with each v1= value in the header (either may match
# during a secret rotation), and reject the delivery if |now - T| > 300 s.X-Capay-Signature: t=1767225600,v1=6f8b4c2d9e0a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f0a2b4c6d8e0f1a3b5c
X-Capay-Event-Id: evt_2n4Kq8Zr41Xa
X-Capay-Event-Type: collection.completed실패한 전달은 고정 일정으로 재시도합니다: 1m, 5m, 30m, 2h, 6h, 12h, 24h, 24h. 연속 8회 실패한 엔드포인트는 비활성화되고 알려 드리므로, 죽은 엔드포인트가 조용히 이벤트를 삼키는 일이 없습니다.
서명 비밀키는 동시에 두 개까지 활성화할 수 있어 이벤트를 잃지 않고 교체할 수 있습니다. 300초 창을 벗어난 것은 모두 거부하고 이벤트 id를 저장해 재전송을 무해하게 만드세요.
나머지 도구
기계가 읽는 명세, 바로 가져올 수 있는 컬렉션, 그리고 그것을 읽는 도구들.