# Circle API
[toc]
# USDC
USD Coin (USDC) é uma stablecoin totalmente reservada em execução em muitos dos principais blockchains do mundo e sempre resgatável 1:1 para dólares americanos.
O preço do USDC está atrelado a $ 1 USD. Seu mecanismo de peg usa uma abordagem simples de garantia de 100%. Isso significa que para cada 1 USDC em circulação, há $ 1 USD mantido em reserva.
O USDC foi projetado a partir da estrutura fiat stablecoin de código aberto desenvolvida pela Circle and Centre. Você pode monitorar os relatórios de atestado sobre as reservas do USDC verificando a página de confiança e transparência do Circle.
As APIs Circle Account e Circle suportam todas as versões nativas do USDC:
Algorand USDC | site de blockchain
Avalanche USDC | site de blockchain
Ethereum USDC | site de blockchain
luxo USDC | site de blockchain
Hedera USDC | site de blockchain
Solana USDC | site de blockchain
USDC estelar | site de blockchain
TRON USDC | site de blockchain
A conta Circle e as APIs Circle também oferecem suporte a versões "ponte" específicas do USDC:
Polígono USDC | site de blockchain
Por que o USDC é relevante no contexto das APIs do Circle?
Desde o início, nós da Circle imaginamos um mundo onde o “dinheiro de todos os dias”, como dólares, euros, ienes, etc., poderia herdar os recursos mais poderosos de moedas digitais como bitcoin:
aberto, global, conectado a qualquer pessoa e qualquer coisa na internet;
rápido, barato e seguro para transmitir.
Representar e armazenar "dinheiro" e processar transferências de "dinheiro" são recursos que cada vez mais empresas exigem em seu núcleo. Aceitar pagamentos, fazer transações com parceiros, participar de comércio pela Internet e diferentes tipos de transações financeiras - todos esses recursos geralmente envolvem representar e armazenar dinheiro em uma conta bancária e lidar com transferências por meio de soluções tradicionais de processamento de pagamentos. Do ponto de vista da tecnologia, essas soluções são tipicamente fechadas, regionais, difíceis de obter, lentas e caras.
As APIs do Circle se integram e utilizam o USDC para representar dinheiro de uma forma nativa da Internet. Os pagamentos com cartão (e outros tipos de) são liquidados em USDC em uma carteira, em oposição ao dinheiro "tradicional" em uma conta bancária. As empresas podem manipular esses fundos por meio de APIs modernas e podem se conectar instantaneamente a qualquer outro serviço ou infraestrutura que também utilize o USDC.
Essa abordagem oferece aos desenvolvedores e empreendedores de todo o mundo uma escolha. A escolha de construir produtos e comércio de uma forma não só mais aberta, global, rápida e barata, mas também onde o próprio conceito de dinheiro é extensível e programável.
O USDC já se tornou uma peça crítica de infraestrutura para centenas de empresas em todo o mundo, tendo sido integrado a tudo, desde carteiras e bolsas digitais a plataformas de valores mobiliários, sistemas de financiamento comercial, produtos de pagamento, poupança e empréstimo e até jogos.
# Limites
| Payment Method | Type of Flow | Minimum Payment Amount| Maximum Payment Amount |
| ------------------ | :----------------: | ----------------- |-----------------:|
| Debit & credit cards| Payments | $0.50 | N/A |
| ACH transfer | Payments | $0.50 | $25,000 |
| ACH transfer | Payouts | $0.50 | $25,000 |
| Wire transfer | Payments | N/A | N/A |
| Wire transfer | Payouts | N/A | N/A|
| SEPA transfer | Payments | $0.01 | Credit: $999,999,999 Instant: $100,000|
| SEPA transfer | Payouts | $0.01 | Credit: $3,000,000Instant: $3,000,000|
# Account
## Master Wallet
Sua conta do Circle tem uma carteira principal que é gerada automaticamente para você assim que você se inscreve.
Esta Master Wallet é o destino para a liquidação dos pagamentos e a origem dos pagamentos, caso você use nossa API de pagamentos ou API de pagamentos.
## Extrato
No endpoint GET /v1/payments poderemos ver todos os depósitos que foram feitos
```
{
"id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
"type": "payment",
"merchantId": "c680d087-7b41-40aa-95a2-68febcdddb22",
"merchantWalletId": "1000002853",
"amount": {
"amount": "1.0",
"currency": "USD"
},
"source": {
"id": "86461e9f-db1a-487f-915b-641138062e7c",
"type": "card"
},
"description": "description",
"status": "pending",
"verification": {
"avs": "not_requested",
"cvv": "not_requested"
},
"cancel": { .. },
"refunds": [],
"fees": {
"amount": "3.0",
"currency": "USD"
},
"trackingRef": "74537600052007895984372",
"errorCode": "payment_failed",
"metadata": {
"email": "satoshi@circle.com",
"phoneNumber": "+14155555555"
},
"riskEvaluation": {
"decision": "denied",
"reason": "3000"
},
"createDate": "2020-04-10T02:29:53.888Z",
"updateDate": "2020-04-10T02:32:19.421Z"
}
```
ou
no endpoint GET v1/businessAccount/deposits
```
{
"id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
"sourceWalletId": "string",
"destination": {
"type": "string",
"id": "string"
},
"source": {
"id": "86461e9f-db1a-487f-915b-641138062e7c",
"type": "card"
},
"amount": {
"amount": "string",
"currency": "string"
},
"fee": {
"amount": "string",
"currency": "string"
},
"status": "string",
}
```
# Pay In
## Wires X ACH
Wires
* Mais rápidas
* Custam mais
* Transações não podem ser revertida
* Transações domésticas e internacionais
* Não tem limites
ACH
* Normalmente de graça
* Levam mais tempo (3 a 4 dias uteis para ocorrer o settlement)
* Transações podem ser revertidas. ex: caso de fraude ou erro
* Transações domésticas
* Limite diário e semanal
* Pode ser configurado para fazer pagamentos recorrentes
## Wires
Primeiro é necessário cirar uma conta bancaria no seguinte endpoint POST /v1/banks/wires
```
BODY:
{
"idempotencyKey":"561c2cd0639e44cd94d6551f0d939efc",
"accountNumber":"749a8c7ebc79428383d9eac99f409c91",
"routingNumber":"MXN",
"billingDetails":{
"name":0,
"city":1500,
"country":0,
"line1":0,
"line2":0,
"district":0,
"postalCode":0
},
"bankAddress":{
"bankName":0,
"city":1500,
"country":0,
"line1":0,
"line2":0,
"district":0
}
}
```
```
Resposta:
{
"data":{
"id":"ee781852-82c7-4989-9f61-a343c3cf5506",
"description":"JPMORGAN CHASE BANK, NA ****6789",
"trackingRef":"CIR2EQS5BM",
"virtualAccountEnabled": true,
"billingDetails":{
"line1":"1 Main Street",
"city":"Boston",
"postalCode":"02201",
"district":"MA",
"country":"US"
},
"bankAddress":{
"bankName":"JPMORGAN CHASE BANK, NA",
"city":"NEW YORK",
"district":"NEW YORK",
"country":"US"
},
"createDate":"2020-07-27T07:17:16.799Z",
"updateDate":"2020-07-27T07:17:16.799Z"
}
}
```
Após a Criação da conta bancária iremos expor os dados do depósito para o cliente usando o seguinte endpoint GET /wires/{id}/instructions
```
Resposta :
{
"data":{
"trackingRef":"CIR2JYD6WT",
"beneficiary":{
"name":"CIRCLE INTERNET",
"address1":"1 MAIN STREET",
"address2":"SUITE 1"
},
"virtualAccountEnabled": true,
"beneficiaryBank":{
"name":"CRYPTO BANK",
"swiftCode":"CRYPTO99",
"routingNumber":"999999999",
"accountNumber":"1000000001",
"address":"1 MONEY STREET",
"city":"NEW YORK",
"postalCode":"10001",
"country":"US"
}
}
}
```
No ambiente de produção, os detalhes da transferência acima representarão os detalhes da conta bancária do Circle para transferências recebidas. O número da conta bancária do beneficiário será um número de conta virtual exclusivo para cada conta bancária vinculada. Essas informações devem ser compartilhadas com o usuário final que inicia a transferência bancária. Assim que os fundos chegarem à infraestrutura bancária da Circle, tentaremos reconciliar esse pagamento e liquidar os fundos em sua conta.
Quado o cliente efetuar o deposito será gerado o seguinte documento:
```
{
"id": "c82a2f41-5ec5-4d86-9395-fcdf0d0da552",
"type": "payment",
"merchantId": "7cbdedb1-d526-46b4-af12-4162a002eb9c",
"merchantWalletId": "1000005019",
"source": {
"id": "cc3ac8e5-4dd7-4061-b465-0d2e7947ce4c",
"type": "wire"
},
"description": "Merchant push payment",
"amount": {
"amount": "1000.00",
"currency": "USD"
},
"fees": {
"amount": "0.00",
"currency": "USD"
},
"status": "paid",
"refunds": [
],
"createDate": "2020-10-15T11:20:01.346Z",
"updateDate": "2020-10-15T11:28:06.117Z"
}
```
:::info
:information_source: Atualização de deposito por webhook e polling
:::
:::warning
:warning: Transferir número de conta virtual e referência de rastreamento
Observe que uma conta bancária criada por APIs do Circle tem um número de conta virtual (atributo 'beneficiaryBank.accountNumber') e uma referência de rastreamento (atributo trackingRef) que é exclusivo dessa conta bancária. Para pagamentos por transferência bancária, é imperativo que o usuário final que inicia a transferência inclua:
(1) Seu número de conta virtual exclusivo como o número da conta do beneficiário quando solicitado pelo banco, ou;
(2) Se as contas virtuais não estiverem habilitadas em sua conta, o usuário final deverá inserir o valor trackingRef no memorando ou no campo de instrução quando solicitado pelo banco. A não indicação da referência de rastreamento, sem a utilização de um número de conta virtual, impossibilita a Circle de conciliar o pagamento - tais transferências serão devolvidas ao remetente.
:::
:::danger
:triangular_flag_on_post: Devido a obrigações regulatórias, nossos sistemas comparam automaticamente as informações da conta bancária (número e roteamento) e do remetente (nome e sobrenome) fornecidas no momento da criação da conta bancária com as informações recebidas nos detalhes da transferência eletrônica (o que o banco remetente transmite) . Quando há incompatibilidades, somos obrigados a falhar no pagamento e devolver os fundos.
Para evitar devoluções, certifique-se de criar uma experiência de usuário que deixe isso claro para os usuários finais, para que eles forneçam as informações corretas da conta bancária e do titular da conta/beneficiário.
:::
### Duvidas
* É necessário chamar o endpoint POST /v1/banks/wires sempre que eu quiser fazer um depósito por wire?
* Esse é o fluxo de depósito wire ou tenho que chamar o endpoint POST v1/payments passado como parâmetro `` "type" : "wire" `` para criar o depósito?
## ACH
ACH Routing Number é um código utilizado para transferências eletrônicas de dinheiro nos Estados Unidos. ACH é a sigla para Automated Clearing House, uma rede de câmaras de compensação bancária coordenada pela NACHA, similar à brasileira Câmara Interbancária de Pagamentos. Por meio da rede de ACHs é que os bancos norte-americanos processam suas transferências interbancárias locais – similares às nossas TED, DOC e pagamento de boletos.
O código ACH ou ACH Routing Number tem 9 dígitos e identifica o banco e o conjunto de agências onde está a conta que vai receber a transferência local. Ele é diferente do ABA Routing Number, utilizado para transferências internacionais.
:::info
:information_source: Para que a Circle se comunique com a Plaid sobre a conta bancária do cliente, você precisará obter um ``processor_token`` da Plaid especificamente para a Circle e compartilhá-lo conosco.
Siga o Guia de integração do círculo da Plaid para obter um fluxo passo a passo. Para resumir, o que você fará é:
Integre-se com o [ Plaid Link](https://plaid.com/docs/auth/partnerships/circle/), que permite que seu cliente faça login em seu banco e retorne um ``public_token`` para você.
1. Use a API do Plaid para trocar o ``public_token`` por um access_token.
2. Use o access_token com a API do Plaid para criar um ``processor_token`` específico do Circle.
3. O ``access_token`` é para uso próprio do seu serviço e o processor_token é o que você compartilha com o Circle. Ele permite que a Circle acesse informações sobre a conta bancária do cliente, que precisaremos para iniciar os pagamentos e desembolsos.
:::
Crie uma conta bancária vinculada
Assim que tiver um ``processor_token`` do ambiente de produção da Plaid ou um processorToken da sandbox do Circle, você estará pronto para vincular a conta ao Circle.
1. Defina ``plaidProcessorToken`` no endpoint Create a bank account (ACH) para criar um link para esta conta no Circle.
2. As contas bancárias vinculadas começam com ``status: pending`` enquanto verificamos o token e buscamos as informações da conta. Assine notificações ou pesquise o objeto de conta bancária que você acabou de criar para descobrir quando o status muda para concluído.
3. Antes de criar um pagamento ou pagamento com uma conta ACH, certifique-se de que esteja com o status: concluído.
:::warning
:warning: Ao criar pagamentos ACH, você precisará obter autorização ACH de seus usuários finais. Isso é para cumprir os regulamentos da NACHA (National Automated Clearing House Association) e ajuda a evitar reversões de pagamento.
:::
Quando a conta ACH for criada poderemos criar um deposito no endpoint POST /v1/payments
```
Body:
{
...,
"verification": "none",
"source": {
"id": "20d8445a-b5f8-437b-ba62-c3b44d554335",
"type": "ach"
}
}
```
:::info
:information_source: Atualização de deposito por webhook e polling
:::
## Crypto Payment
Primeiro é necessário criar intenção de depósito no seguinte endpoint POST /v1/paymentIntents
```
Body:
{
"idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
"amount": {
"amount": "1.00",
"currency": "USD"
},
"settlementCurrency": "USD"a,
"paymentMethods": [
{
"type": "blockchain",
"chain": "ETH"
}
]
}
```
```
Resposta:
{
"data": {
"id": "6e4d4047-db14-4c09-b238-1215aee50d03",
"amount": {
"amount": "1.00",
"currency": "USD"
},
"amountPaid": {
"amount": "0.00",
"currency": "USD"
},
"settlementCurrency": "USD",
"paymentMethods": [
{
"type": "blockchain",
"chain": "ETH"
}
],
"paymentIds": [],
"timeline": [
{
"status": "created",
"time": "2022-07-21T20:13:35.579331Z"
}
],
"createDate": "2022-07-21T20:13:35.578678Z",
"updateDate": "2022-07-21T20:19:24.859052Z",
}
}
```
:::warning
:warning: Circle não retornamos de forma síncrona o endereço blockchain do depósito, é retornado através de webhook ou por HTTP request
:::
Payment intent webhook com o endereço de deposito
```
{
"clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
"notificationType": "paymentIntents",
"version": 1,
"customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
"paymentIntent": {
"id": "6e4d4047-db14-4c09-b238-1215aee50d03",
"amount": { "amount": "1.00", "currency": "USD" },
"amountPaid": { "amount": "0.00", "currency": "USD" },
"settlementCurrency": "USD",
"paymentMethods": [
{
"type": "blockchain",
"chain": "ETH",
"address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
}
],
"fees": [
{ "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
],
"paymentIds": [],
"timeline": [
{ "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
{ "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
],
"createDate": "2022-07-21T20:13:35.578678Z",
"updateDate": "2022-07-21T20:13:38.186831Z",
"expiresOn": "2022-07-21T21:13:38.087275Z"
}
}
```
Assim que o endereço de depósito for adquirido ``paymentMethods.address``, você o fornecerá ao cliente junto com o valor e a moeda a ser paga. O endereço de depósito pode ser apresentado de duas formas 1) como texto simples que pode ser facilmente copiado 2) como um código QR a ser escaneado em um aplicativo.
Quado o cliente efetuar o deposito será gerado o seguinte documento
```
{
"clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
"notificationType": "payments",
"version": 1,
"customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
"payment": {
"id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
"type": "payment",
"status": "paid",
"amount": { "amount": "1.00", "currency": "USD" },
"fees": { "amount": "0.01", "currency": "USD" },
"createDate": "2022-07-21T20:16:35.092Z",
"updateDate": "2022-07-21T20:19:24.719Z",
"merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
"merchantWalletId": "1000999922",
"paymentIntentId": "6e4d4047-db14-4c09-b238-1215aee50d03",
"settlementAmount": { "amount": "1.00", "currency": "USD" },
"depositAddress": {
"chain": "ETH",
"address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
},
"transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
}
}
```
:::info
:information_source: Atualização de deposito por webhook e polling
:::
A confirmação de pagamento é feita através de webhook ou polling
## Apple Pay
Crie um Payment Token no endpoint POST /v1/paymentTokens
```
Body:
{
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"type": "applepay",
"tokenData": {
"version": "EC_v1",
"data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+...T6Ms7PhiNZpuGEE2QE=",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQEx.../WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj.../zlsw==",
"publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
"transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
}
}
```
```
Resposta:
{
"data": {
"id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",
"type": "applepay",
"expiresOn": "2022-01-18T19:20:00Z",
"cardDetails": {
"expMonth": 1,
"expYear": 2020,
"network": "VISA",
"last4": "0123",
"bin": "401230",
"fundingType": "credit",
"issuerCountry": "US"
},
"createDate": "2020-04-10T02:13:30.000Z",
"updateDate": "2020-04-10T02:13:30.000Z"
}
}
```
Crie um pagamento utilizando o token conseguido no passo acima no endpoint POST v1/payment
```
Body:
{
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"metadata": {
"email": "satoshi@circle.com",
"sessionId": "DE6FA86F60BB47B379307F851E238617",
"ipAddress": "244.28.239.130"
},
"amount": {
"amount": "3.14",
"currency": "USD"
},
"autoCapture": true,
"verification": "none",
"source": {
"id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",
"type": "paymenttoken"
},
"description": "Payment"
}
```
```
Resposta :
{
"data": {
"id": "e6b8d255-e909-4e0f-ae58-aece722bf9fe",
"type": "payment",
"merchantId": "b42af422-702d-4787-90c8-f4a84440ec53",
"merchantWalletId": "0123456789",
"source": {
"id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",
"type": "paymenttoken"
},
"description": "Payment",
"amount": {
"amount": "3.14",
"currency": "USD"
},
"status": "pending",
"captured": false,
"refunds": [],
"createDate": "2022-03-10T14:10:47.665Z",
"updateDate": "2022-03-10T14:10:47.900864Z"
}
}
```
:::warning
:warning: Para adquirir um token de pagamento da Apple, você precisará criar uma conta de desenvolvedor da Apple, registrar-se como comerciante e adquirir credenciais de acesso. Por favor, trabalhe com um representante designado do Círculo para trabalhar neste processo.
:::
### Duvidas
* Payments por apple pay possui webhook? ou apenas polling?
## SEPA
A transferência de crédito SEPA é uma transferência de crédito em conformidade com o padrão europeu de transferência de crédito. Pode ser utilizado para todos os tipos de pagamentos em euros dentro da área única de pagamentos em euros.
As transferências a crédito SEPA são geralmente creditadas ao destinatário o mais tardar no dia útil seguinte, enquanto as transferências a crédito instantâneas SEPA são transferidas em segundos dentro da área de pagamentos em euros. Sempre que possível, a maioria das transferências de crédito SEPA são compensadas para outros bancos na Finlândia e na Europa em tempo real como transferências de crédito instantâneas SEPA.
Os pagamentos em toda a área de pagamentos em euros estão se tornando mais rápidos à medida que mais e mais bancos adotam o serviço de transferência instantânea de crédito SEPA para substituir as transferências de crédito SEPA padrão.
* Os fundos são transferidos e disponibilizados para uso dentro de 10 segundos após o envio do pagamento 24 horas por dia, 7 dias por semana, todos os dias do ano.
* As transferências interbancárias na Finlândia não têm um limite superior baseado em euros. Os bancos de outros países também pertencem ao Grupo Fechado de Usuários que não possui limite máximo. No esquema SEPA, o limite máximo geral é agora de 100.000 euros.
* O mesmo serviço é utilizado em toda a SEPA entre os bancos participantes.
* Os maiores bancos da Finlândia e de toda a SEPA adotaram o serviço, pelo menos para aceitar transferências instantâneas de crédito recebidas. Os bancos adotarão o serviço com base em seu próprio cronograma e começarão a prestar o serviço em etapas.
Primeiro é necessário cirar uma conta bancaria no seguinte endpoint POST /v1/banks/sepa
```
Body:
{
"idempotencyKey": "6ae62bf2-bd71-49ce-a599-165ffcc33680",
"walletId": "${YOUR_WALLET_ID}",
"iban": "IE31100400480532013000",
"billingDetails": {
"name": "Satoshi Nakamoto",
"city": "Dublin",
"country": "IE",
"line1": "1 Dublin Street",
"postalCode": "D01 AY67"
}
}
```
```
Resposta?
{
"data": {
"id": "a6ba73a8-cc77-46c5-bbbc-ce7a97ecb372",
"status": "pending",
"description": "Bank of Ireland ****0010",
"trackingRef": "CIR13FB13A",
"fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2",
"billingDetails": {
"name": "Satoshi Nakamoto",
"city": "Dublin",
"country": "IE",
"line1": "1 Dublin Street",
"postalCode": "D01 AY67"
},
"createDate": "2020-04-10T02:13:30.000Z",
"updateDate": "2020-04-10T02:13:30.000Z"
}
}
```
Após a Criação da conta bancária iremos expor os dados do depósito para o cliente usando o seguinte endpoint GET v1/banks/sepa/${BANK_ACCOUNT_ID}/instructions
```
Resposta:
{
"data": {
"trackingRef": "CIR3ZN75QG",
"beneficiary": {
"name": "CIRCLE LLC",
"address1": "99 HIGH STREET",
"address2": "LEVEL 17 SUITE 1701"
},
"beneficiaryBank": {
"name": "LHV Pank",
"address": "Tartu mnt 2, 10145 Tallinn",
"postalCode": "92037",
"country": "EE",
"bic": "LHVBEE22XXX",
"iban": "EE691269412446551399"
}
}
}
```
Quado o cliente efetuar o deposito será gerado o seguinte documento
```
{
"data": {
"id": "c82a2f41-5ec5-4d86-9395-fcdf0d0da552",
"type": "payment",
"merchantId": "7cbdedb1-d526-46b4-af12-4162a002eb9c",
"merchantWalletId": "1000005019",
"source": {
"id": "cc3ac8e5-4dd7-4061-b465-0d2e7947ce4c",
"type": "sepa"
},
"description": "Merchant push payment",
"amount": {
"amount": "1000.00",
"currency": "USD"
},
"fees": {
"amount": "0.00",
"currency": "USD"
},
"status": "paid",
"refunds": [],
"createDate": "2020-10-15T11:20:01.346Z",
"updateDate": "2020-10-15T11:28:06.117Z"
}
}
```
:::warning
:warning: Observe que uma conta bancária criada por APIs do Circle tem uma referência de rastreamento (atributo ``trackingRef``) que é exclusivo dessa conta bancária. Para pagamentos por transferência bancária SEPA, é imperativo que o utilizador final que inicia a transferência inclua esse valor no campo de ``payment reference`` quando solicitado pelo seu banco. A não indicação da referência de rastreamento impossibilita a Circle de conciliar o pagamento - tais transferências serão devolvidas ao remetente.
:::
:::danger
:triangular_flag_on_post: Devido a obrigações regulatórias, nossos sistemas comparam automaticamente as informações da conta bancária (iban) e do remetente (nome e sobrenome) fornecidas no momento da criação da conta bancária com as informações recebidas nos detalhes da transferência SEPA (o que o banco remetente transmite). Quando há incompatibilidades, somos obrigados a falhar no pagamento e devolver os fundos.
Para evitar devoluções, certifique-se de criar uma experiência de usuário que deixe isso claro para os usuários finais, para que eles forneçam as informações corretas da conta bancária e do titular da conta/beneficiário.
:::
## Cartão
:construction_worker:
## Duvidas
* Todas as criações de deposito teremos que chamar POST /v1/payments ou é apenas para depósitos ACH e Cartão?
* Existe alguma diferença entre a api core e payment?
# PayOut
## Crypto Payouts
A API Crypto Payouts permite enviar USDC, EUROC, BTC, ETH e MATIC (no Polygon). A API também virá com uma funcionalidade de troca incorporada para converter de e para USDC. Se você não estiver realizando uma troca, pode enviar diretamente a moeda sob custódia (por exemplo, ETH sob custódia pode ser pago em ETH sem trocas). Se você estiver procurando por trocas, abaixo estão as moedas de origem e destino e a cadeia de destino que circle oferece.
Primeiro criaremos o endereço que enviaremos nossos fundos no POST /v1/addressBook/recipients
```
Body:
{
"idempotencyKey": "9352ec9e-5ee6-441f-ab42-186bc71fbdde",
"chain": "ETH",
"address": "0x65BFCf1a6289a0b77b4D3F7d12005a05949FD8C3",
"metadata": {
"email": "satoshi@circle.com",
"bns": "testbns",
"nickname": "test nickname desc"
}
}
```
```
Resposta:
{
"data": {
"id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
"chain": "ETH",
"address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
"metadata": {
"nickname": "test nickname desc",
"email": "satoshi@circle.com",
"bns": "testbns"
},
"status": "pending",
"updateDate": "2022-09-22T14:16:34.985353Z",
"createDate": "2022-09-22T14:16:34.985353Z"
}
}
```
Antes de fazer o Payout é necessario verificar o status do recipiente:
Feito po polling ou webhook
```
{
"clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
"notificationType": "addressBookRecipients",
"version": 1,
"customAttributes": {
"clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
},
"addressBookRecipient": {
"id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
"chain": "ETH",
"address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
"metadata": {
"nickname": "test nickname desc",
"email": "satoshi@circle.com",
"bns": "testbns"
},
"status": "active",
"updateDate": "2022-09-22T14:16:34.985353Z",
"createDate": "2022-09-22T14:16:34.985353Z"
}
}
```
Para completar o payout é necessario chamar o endpoint POST /v1/payouts
```
Body:
{
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"source": {
"type": "wallet",
"id": "12345"
},
"identities": [
{
"type": "individual",
"name": "Satoshi Nakamoto",
"addresses": [
{
"line1": "100 Money Street",
"line2": "Suite 1",
"city": "Boston",
"district": "MA",
"postalCode": "01234",
"country": "US"
}
]
}
],
"destination": {
"type": "address_book",
"id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
},
"amount": {
"amount": "3000.14",
"currency": "USD"
},
"toAmount": {
"currency": "ETH"
}
}
```
```
Resposta:
{
"data": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"sourceWalletId": "12345",
"destination": {
"type": "address_book",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": {
"amount": "3000.14",
"currency": "USD"
},
"toAmount": {
"currency": "ETH"
},
"status": "pending",
"updateDate": "2020-04-10T02:13:30.000Z",
"createDate": "2020-04-10T02:13:30.000Z"
}
}
```
:::info
Atualização de status do payout por webhook ou polling
:::
## Wire PayOut
Primeiro criaremos uma conta bancária com as informações para onde iremos enviar fundos no POST /v1/banks/wires
```
Body:
{
"idempotencyKey":"6ae62bf2-bd71-49ce-a599-165ffcc33680",
"beneficiaryName":"John Smith",
"accountNumber":"123456789",
"routingNumber":"021000021",
"billingDetails":{
"name":"John Smith",
"city":"Boston",
"country":"US",
"line1":"1 Main Street",
"district":"MA",
"postalCode":"02201"
},
"bankAddress":{
"country":"US"
}
}
```
```
Resposta:
{
"data":{
"id":"a6ba73a8-cc77-46c5-bbbc-ce7a97ecb372",
"description":"JPMORGAN CHASE BANK, NA ****6789",
"billingDetails":{
"district":"MA",
"country":"US"
},
"bankAddress":{
"bankName":"JPMORGAN CHASE BANK, NA",
"city":"NEW YORK",
"district":"NEW YORK",
"country":"US"
},
"createDate":"2020-07-27T07:22:53.120Z",
"updateDate":"2020-07-27T07:22:53.120Z"
}
}
```
Para completar o payout é necessario chamar o endpoint POST /v1/payouts
```
Body:
{
"idempotencyKey":"6ae62bf2-bd71-49ce-a599-165ffcc33680",
"beneficiaryName":"John Smith",
"accountNumber":"123456789",
"routingNumber":"021000021",
"billingDetails":{
"name":"John Smith",
"city":"Boston",
"country":"US",
"line1":"1 Main Street",
"district":"MA",
"postalCode":"02201"
},
"bankAddress":{
"country":"US"
}
}
```
```
Resposta:
{
"data":{
"id":"2f0d9c44-c86d-4c1a-a33c-d436b8148879",
"sourceWalletId":"1000005019",
"createDate":"2020-07-27T07:59:09.350Z",
"updateDate":"2020-07-27T07:59:09.350Z",
"destination":{
"type":"wire",
"id":"a6ba73a8-cc77-46c5-bbbc-ce7a97ecb372",
"name":"JPMORGAN CHASE BANK, NA ****6789"
},
"amount":{
"amount":"150.00",
"currency":"USD"
},
"status":"pending"
}
}
```
:::info
Atualização de status do payout por webhook ou polling
:::
### Contas bancárias para transferências eletrônicas em diferentes países
As informações necessárias para iniciar um pagamento por transferência bancária variam dependendo do país da conta bancária de destino.
Ao criar uma conta bancária a ser usada para pagamentos por transferência eletrônica usando criar um endpoint de conta bancária, você terá que fornecer atributos de dados ligeiramente diferentes, dependendo do país da conta bancária.
Veja a tabela abaixo para as 3 opções diferentes em termos de atributos de dados necessários e países.
| Option | Bank Account Country | Minimum Payment Amount|
| ------------------ | :----------------: | ----------------------- |
| 1 | United States | ``accountNumber`` ``routingNumber`` (ABA) ``country`` (in ``bankAddress``)|
| 2 |Andorra, Austria, Azerbaijan, Belgium, Bulgaria, Croatia, Denmark, Estonia, Finland, France, Germany, Gibraltar, Greece, Guatemala, Holy See (Vatican City State), Hungary, Iceland, Ireland, Israel, Italy, Jordan, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Monaco, Netherlands, Norway, Poland, Portugal, Romania, San Marino, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey, United Arab Emirates, United Kingdom, Virgin Islands (British)| ``iban city`` (in ``bankAddress``) ``country`` (in ``bankAddress``)|
| 3 | Angola, Anguilla, Argentina, Australia, Benin, Bermuda, Brazil, Burkina Faso, Cambodia, Cameroon, Canada, Cayman Islands, Chad, Chile, Guam, Guernsey, Hong Kong, India, Indonesia, Isle Of Man, Japan, Jersey, Kenya, Korea, Madagascar, Malawi, Malaysia, Mexico, Mozambique, New Zealand, Niger, Peru, Philippines, Puerto Rico, Senegal, Singapore, South Africa, Taiwan, Tanzania, Thailand, United States Outlying Islands, Uzbekistan, Viet Nam, Virgin Islands (U.S.) | ``accountNumber`` ``routingNumber`` (SWIFT / BIC)``bankName`` (in ``bankAddress``) ``city`` (in ``bankAddress``) ``country`` (in ``bankAddress``) |
Sign in with Wallet
Connect another wallet