Circle

Pg

Index

What is CIRCLE PG?

API

위기 관리

What is
Circle Pg?

1. 글로벌 결제


2. 유연한, 프로그래밍 방식 지불 


3. 강력한 계정 인프라

1. 글로벌 결제


2. 유연한, 프로그래밍 방식 지불 


3. 강력한 계정 인프라

1. 글로벌 결제


2. 유연한, 프로그래밍 방식 지불 


3. 강력한 계정 인프라

1. 글로벌 결제


2. 유연한, 프로그래밍 방식 지불 


3. 강력한 계정 인프라

Circle is...

Authentication

Authorization: Bearer {YOUR_API_KEY}

Simple...!

멱등원 요청(Idempotent Requests) 지원

- 결제 진행중 문제가 발생했을때 API요청을 안전하게 재시도 할수 있습니다.

???

당연한거 아닌가?

우리가 API 서버에 요청하는 것들을 보통 4가지로 분류함

- 쓰기(Create)

- 읽기(Read)

- 수정(Update)

- 삭제(Delete)

앞자만 따서 CRUD라고 줄여서 말하고,

'자원의 이름으로 구분하여 자원의 상태를 주고받는 것'

우리는 REST( REpresentational State Transfer) 요청이라고 부르기로 했어요.

멱등하다

연산을 여러 번 적용하더라도 결과값이 달라지지 않는 일.

아까 뭐 멱등 뭐시기 요청이랬던거 같은데...?

여러번 시도해도 문제 없는 요청 (멱등하다)

여러번 시도하면 안되는 요청 (멱등하지 않다)

Read
- 여러번 요청해도 불변. 계속 보여달라 요청해도 값은 불변.

Update
- 이게 왠지 여러번 하면 안될 것 같지만, 여러번 요청해도 같은 지향점으로 변경하는 요청이기 때문에 n번 요청 해도 결과는 불변

Delete
- 역시나 얘도 하면 안될 것 같지만, 재시도 요청시 첫번째를 제외한 나머지 요청들은 그냥 예외처리로 분류되고 데이터는 단일 데이터 하나를 지운 상태로 결과 불변.

Create

- 이놈이 문제..!

- 여러번 시도 되면 계속 생성 (제대로 처리되어있지 않은 상태였을때)

- 혹시 결제라도 여러번 되어버리면!!?!!

우리는 고민에 빠지게 됩니다.

구조로 해결!

Circle API resource

Payment Object
Payout Object
Transfer Object

Circle의 API는 결제, 출금, 송금 및 관련 내용을 나타내는 여러개의 Resource를 중심으로 구축되어있음.

예시는 payment object

Circle API Notifications

{

"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",

"notificationType": "payments",

"payment": {...}

}

Name	Type	Description	Sample
clientId	UUID	Client identifier	c60d2d5b-203c-45bb-9f6e-93641d40a599
notificationType	String	The type of notification	payments
version	int

구조

예시

예시의 payment 위치가 여러 형태의 resource로 전달 됨

payment : Confirmed | Failed | Refund | Cancel

reversal(취소 요청), chargeback(지불 거절), payout,

sattlement(정산 흐름), card, ach, wire, transfer

결제가 성공한 후 우리쪽 서버에 callback 해주는 형태가 아닌, notifications endpoint 하나를 열어서 여러가지 정보를 알려줌

How to?

알림을 받기 위한 endpoint를 열어놓고 푸시를 받는 형태

샘플코드는 노드로 구성되어있음

- node httpserver.js 127.0.0.1 8080

샘플 내부 코드 확인해 본 결과 POST로 요청으로 들어오는 2가지 케이스만 정의되어 있었으며 관련 내용이 들어온 것들은 로그찍는게 전부

- SubscriptionConfirmation

- Notification

Pagination

and

Filtering

대부분의 컬렉션 리소스에서 사용할 수 있는 공통 기능

날짜 범위

- from, to로 지정

예시) https://api-sandbox.circle.com/v1/payments?

from=2020-01-01T00:00:00Z&to=2020-01-31T23:59:59Z

Pagination

- HTTP link Header 지원 (self, first, next, prev)

- pageAfter

?to=2020-06-02T12:00:00Z&pageAfter=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e

-pageSize
?to=2020-06-02T12:00:00Z&pageSize=50&pageAfter=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e

HTTP link Header 지원

Link: <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageAfter=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e>; rel="self",

<https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50>; rel="first",

<https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageAfter=6f14b84d-7a98-4675-a6b9-d7b0c1912091>; rel="next",

<https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageBefore=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e>; rel="prev"

Common Error Responses

일반 오류 형식과 확장 오류 형식

확장 오류 형식

일반 오류 형식

ACH

ACH(Automated Clearing House) 송금이란?

자동 어음 교환 시스템을 말하며, 미국 은행 간의 전자 송금 방식으로, ACH 네트워크를 통해 처리되는 송금 방식을 말해요.

자세한건 아래의 URL을 참고해주시기 바랍니다!

https://wise.com/kr/blog/what-is-ach-transfer

간단하게 특징만 정리하면,

- Visa나 Mastercard와 같은 카드 네트워크를 경유하지 않으므로 적은 수수료로 송금을 진행할 수 있음

- 은행 계좌로 송금이 진행되기 때문에 결제 수단이 만료될 걱정이 없음

- 법인과 개인 모두 미국 은행 계좌만 있다면 ACH 송금을 진행할 수 있음

- 전신 송금은 상대적으로 송금 수수료가 비싸지만 보통 2영업일 이내에 송금이 처리되지만, ACH 송금은 수수료가 무료이거나 상대적으로 저렴한 대신 송금이 완료되기까지 3영업일 이상이 걸릴 수 있다는 차이점이 있음

Swap USDC Across

Blockchains

블럭체인간 USDC 스왑

블럭체인 간 USDC 교환 가능한 목록

(우리는 Solana 이므로 솔라나 기준 데이터)

1. Avalanche USDC

2. Algorand USDC

3. Ethereum USDC

4. Flow USDC

5. Hedera USDC

6. Stellar USDC

7. TRON USDC

API 키 받기
이더리움 블록체인에서 USDC받기
- 지갑 만들기
- 입금 주소 생성
- USDC 송금
  - 테스트 환경 제공 (다음 페이지 상세 설명)
이체 현황 확인
알고랜드 블록체인에 USDC보내기
이체 현황 확인

Ethereum Goerli test network라는 것이 존재하며,
관련 test USDC를 발급받을 수 있음. (https://usdcfaucet.com/)
이더스캔에서 공식적으로 서브도메인으로 제공

Blockchain Confirmations

블럭체인의 트랜잭션은 블록으로 패키징되는데, 최근에 생성된 블록을 무효화 하는 규칙이 포함되는 경우가 많다.

이러한 경우 관련 내용을 기록 재작성하는데, 무효화된 블록에 포함된 모든 거래를 무효화하여 이전된 자금을 원래 소유자에게 반환합니다.

공격자가 결제후 재구성하는 형태로 (특정 방법론을 따서 "51%공격") 결제는 반환하고 카드 구매는 완료되는 경우가 발생할 수 있음.

따라서, 그에대한 보안을 증대하기 위해 전송을 인식하기 전에 여러 블록을 기다릴 수 있는데, 주어진 블록 이후로 많은 블록이 처리될 수록 해당 블록이 무효화 될 가능성이 줄어듬.

따라서, 딜레이를 살짝 주면, 재구성으로 인한 위험을 최소화 할 수 있음.

솔라나는 대기하는 블록의 수를 1개, 시간은 약 400밀리초를 지연함으로써 위와 같은 위험을 최소화함.

참고로 비트코인은 블록 4개 대략 40분, 이더리움은 블록 12개 3~5분

API

Errors

API 오류

1. API 응답 오류

- 우리가 흔히 알고 있는 validation 오류

- ex) 필수 값 (결제자 정보, 이름, email주소 등이 없다)

2. 엔티티 오류

- 출금 요청에 대한 응답 같은 케이스

- 제 3자에 의해서 발생하는 에러 카드사에서의 실패, 은행에서의 실패

- 자금 부족, 잘못된 카드 번호, 카드 번호 없음, 카드 만료

쉽게 정리하면,

API 응답 오류 : 요청 (우리와 circle 간의) 문제 & circle에서의 문제

엔티티 오류 : circle과의 요청은 정상적으로 되었는데 외부 요인으로 발생하는 문제

API status

https://status.circle.com/

그래프에서의 막대기 1개는 1일을 의미

일별 평균 응답속도

일별 이슈 리포트

(먼저든 생각)
엄청 신뢰 간다 vs 저 자체를 믿을수 있을까?

Channels

Dynamic billing descriptors

Channels enable you to display dynamic billing descriptors to your customers for each part of your business. To get started, simply reach out to your Account Manager with your preferred list of channel names with their respective card descriptors and ACH descriptors. Please also indicate which channel will be the default channel. The default channel will be used for scenarios where a channel is not selected for a transaction.

From there, you can build channels into your workflow by pulling a list of channels through GET /v1/channels and sending the selected channel’s id when creating a transaction.

채널을 운영하여 비즈니스 별 과금 내용을 분리할 수 있다정도로 이해 되지만 정확하게 어떤 식인지 잘 모르겠습니다.

API

결제 API

상거래 앱이나 웹사이트에서 상품이나 서비스에 대한 카드, 전신환 또는 ACH 결제를 연동할 수 있습니다.
암호화폐 교환을 위한 신용/직불 카드 또는 전신/ACH 송금을 구축할 수 있습니다.
저축, 대출, 투자 또는 P2P 결제 상품을 위해 카드 또는 전신환/ACH 예금을 가져올 수 있습니다.
은행 송금 또는 ACH를 통해 최종 사용자의 은행 계좌로 판매 대금을 지급할 수 있습니다.

결제 API로 할수 있는 일..!

카드 결제
전신 송금(은행 이체)
SEPA 결제
카드 결제 수락
결제 후 처리
금액 및 한도
지원 국가
지원되는 통화
지원되는 결제 수단
샘플 지불 어플리케이션
카드, 은행 및 지불 위험 평가
관심 목록

SEPA (Single Euro Payments Area) 이체란?

유로존 내의 모든 계좌로 현금 없이 유로화 지불을 할 수 있는 결제 시스템을 말합니다. SEPA의 목적은 국가 간 유로화 은행 이체를 보다 저렴하고, 안전하며, 빠르게 하는 것입니다.

다른 결제 시스템과 달리 다른 참여 국가로 송금하는 데 추가 요금이 부과되지 않습니다.

카드 결제

1. Get an API key

2. Install the sample application

3. Accept your first card payment

4. Check the status of your card payment

API는 [가이드] 문서보다는...[API 참조]쪽 내용을 보는게 좋겠습니다..!

카드 결제 흐름

카드 정보는 브라우저에서 암호화!

페이지 로드 암호화에 사용되는 openPgP.js를 이용하여 클라이언트에서 카드정보를 암호화하기 때문에 서버측에서 알 수 없음.

sandbox전용 테스트 카드 제공

결제 금액으로 응답코드 지정

CVV 검증

비슷한 이름중에 CVC라는 것도 들어본거 같은데..?

CVV는 비자카드 CVC 마스터 카드에서 사용하는 용어일뿐 의미나 용도는 비슷함

카드 번호를 사기치거나, 랜덤으로 입력하는 것을 방지 하기 위한 코드

카드사에서 발행할때 해당 카드 번호에 대한 검증 코드로써 만든 것.

AVS 검증

- CVV처럼 카드 사기를 방지하는데 사용되는 또 다른 매커니즘인데, 이건 카드 발행시 등록했던 주소를 기반으로 검증하는 것.

- 미국, 캐나다, 영국에서 발급된 카드만 적용

카드 결제를 지원하는 국가

Åland Islands, Algeria, American Samoa, Andorra, Angola, Anguilla, Antarctica, Antigua and Barbuda, Argentina, Armenia, Aruba, Australia, Austria, Azerbaijan, Bahrain, Bangladesh, Belgium, Belize, Benin, Bermuda, Bhutan, the Plurinational State of Bolivia, Bonaire, Sint Eustatius and Saba, Bosnia and Herzegovina, Bouvet Island, Brazil, the British Indian Ocean Territory, Brunei Darussalam, Bulgaria, Burkina Faso, Burundi, Cabo Verde, Cameroon, Canada, the Cayman Islands, Chad, Chile, China, Christmas Island, the Cocos (Keeling) Islands, Colombia, the Comoros, the Congo, the Cook Islands, Costa Rica, Côte d'Ivoire, Croatia, Curaçao, Cyprus, Czechia, Denmark, Djibouti, Dominica, the Dominican Republic, Ecuador, Egypt, El Salvador, Equatorial Guinea, Eritrea, Estonia, Eswatini, Ethiopia, the Falkland (Islas Malvinas), the Faroe Islands, Fiji, Finland, France, French Guiana, French Polynesia, the French Southern Territories, Gabon, the Gambia, Georgia, Germany, Gibraltar, Greece, Greenland, Grenada, Guadeloupe, Guam, Guatemala, Guernsey, Guinea, Guyana, Haiti, Heard Island and McDonald Islands, the Holy See, Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Ireland, Isle of Man, Israel, Italy, Japan, Jersey, Jordan, Kazakhstan, Kenya, Kiribati, the Republic of Korea, Kuwait, Kyrgyzstan, the Lao People's Democratic Republic, Latvia, Lebanon, Lesotho, Liberia, Liechtenstein, Lithuania, Luxembourg, Macao, Madagascar, Malawi, Malaysia, Maldives, Malta, the Marshall Islands, Martinique, Mauritania, Mayotte, Mexico, ...

은행 송금을 지원하는 국가

Andorra, Angola, Anguilla, Argentina, Australia, Austria, Azerbaijan, Belgium, Benin, Bermuda, Brazil, Bulgaria, Burkina Faso, Cambodia, Cameroon, Canada, the Cayman Islands , Chad, Chile, Croatia, Denmark, Estonia, Finland, France, Germany, Gibraltar, Greece, Guam, Guatemala, Guernsey, the Holy See, Hong Kong, Hungary, Iceland, India, Indonesia, Ireland, Isle of Man, Israel, Italy, Japan, Jersey, Jordan, Kenya, the Republic of Korea, Latvia, Liechtenstein, Lithuania, Luxembourg, Madagascar, Malawi, Malaysia, Malta, Mexico, Monaco, Mozambique, the Netherlands, New Zealand, the Niger, Norway, Peru, the Philippines, Poland, Portugal, Puerto Rico, Romania, San Marino, Senegal, Singapore, Slovakia, Slovenia, South Africa, Spain, Sweden, Switzerland, Taiwan, the United Republic of Tanzania, Thailand, Turkey, the United Arab Emirates, the United Kingdom of Great Britain and Northern Ireland, the United States Minor Outlying Islands, the United States of America, Uzbekistan, Viet Nam, Virgin Islands (British), Virgin Islands (U.S.)

China는 없습니다..!

지불 API

지불은 별 다른 내용이 없습니다.

1. Decide Where to Send Funds From
- 이게 무슨 말인가 하면, 개별 사용자 또는 다른 유형의 구조를 나타내는 하위 지갑이 있고 그중 하나를 지불 소스로 사용하는 경우, 어느 지갑에서 보낼지 결정하는 것. 한개의 지갑 (여기서 옴니버스 지갑이라는 표현을 사용함)을 사용하는 경우에는 그냥 옴니버스 지갑에서 출금 

2. Fund Your Source Wallet
- 지갑에 출금할 돈이 있는지 확인할 것. (이건 진짜 자리 채울라고 한건가?)

3. Create the Bank Account You Will Send the Payout To
- 지불금을 보내려는 은행 계좌를 생성하는 API를 호출
[POST] https://api-sandbox.circle.com/v1/banks/wires

4.  Send the Payout
출금 신청! 
[POST] https://api-sandbox.circle.com/v1/payouts

출금 Flow

Bank Accounts for Wire Transfers in Different Countries

테스트 환경 지원 (Wire, SEPA)

- 지불에 대한 특정 오류 코드를 발생시키고 싶으면 각각 금액을 달리함으로써 해당 오류를 발동 시킬수 있습니다.

6.21, 6.37

8.11, 8.09

왜 이렇게 했을까요...?

계정 API

기존 은행 계좌 구조의 복잡성을 처리하지 않고도 미국 달러, BTC 및 ETH 표시 디지털 잔액을 제품 또는 서비스에 포함할 수 있습니다.

호스트 계정 간 또는 온체인 연결을 통한 원활한 자금 이체를 포함하여
고객을 위한 계정 인프라를 관리합니다.

지갑에서 쓰이는 기능과 거의 대부분 매칭 된다고 생각하면 됩니다..!

마스터 지갑 생성, 보내기, 받기

실제 API Reference 메뉴에서도 이 부분은 다른 메뉴에 편입되어 따로 설명이 되어 있지 않습니다.

위기 관리

위험은 무엇입니까?

직불/신용 카드 결제 또는 ACH 결제를 수락하는 경우 지불 거절 이라는 고객 분쟁을 통해 이러한 결제가 취소될 위험을 수락하는 것 입니다. 이러한 지불 거절은 여러 가지 이유가 있을 수 있으며 판매 손실 및/또는 이와 관련된 수수료로 인한 재정적 손실을 초래할 수 있습니다.

지불 거절은 비즈니스 시간과 비용을 낭비할 수 있습니다. 지불을 수락하는 판매자로서 귀하의 계정은 지불 거절로 인한 모든 손실에 대해 책임이 있으며 귀하는 특정 정보로 응답할 책임이 있습니다.

거래를 안전하게 보호하는 것이 중요하며 Circle은 지불 거절을 방지하고 대응하는 데 필요한 도구를 지원합니다.

Circle pg

By xesper

Circle

Pg

Index

What is Circle Pg?

Circle is...

Authentication

멱등원 요청(Idempotent Requests) 지원

멱등하다

Circle API Notifications

Pagination

and

Filtering

Common Error Responses

ACH

Swap USDC Across

Blockchains

Blockchain Confirmations

API

Errors

API status

Channels

API

결제 API

지불 API

출금 Flow

계정 API

위기 관리

Circle pg

More from xesper

What is
Circle Pg?