diff --git a/CHANGELOG.md b/CHANGELOG.md index ae3b756..6215964 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,33 @@ # Changelog +## [1.1.0](https://github.com/circlefin/openapi-internal/compare/v1.0.3...v1.1.0) (2022-11-17) + + +### New Features + +* add address book endpoints +* add exchange rates endpoint +* add google pay and apple payment tokens +* crypto payouts refactor +* refactor crypto and fiat payout models + + +### Fixes + +* add chargeback status to GET chargebacks API response +* add fundingType field to get cards endpoint +* add openapi tag descriptions +* add signet as a destination type for payouts +* add signet as business destination req type +* add toAmount to fiat payouts +* fix incorrect list all payouts source param description +* model name typos and duplicates +* move payment intents into payments doc +* move transfers endpt out of payments and payouts +* rm crypto payments doc +* rm instances of readOnly +* rm on-chain payments and payouts + ## [1.0.3](https://github.com/circlefin/openapi-internal/compare/v1.0.2...v1.0.3) (2022-09-26) diff --git a/VERSION b/VERSION index 21e8796..9084fa2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.3 +1.1.0 diff --git a/openapi/json/account.json b/openapi/json/account.json index 73ccd4a..1e77c1d 100644 --- a/openapi/json/account.json +++ b/openapi/json/account.json @@ -2,38 +2,46 @@ "openapi": "3.0.2", "servers": [ { - "url": "api-sandbox.circle.com" + "url": "https://api-sandbox.circle.com" } ], "info": { - "version": "1.0.3", + "version": "1.1.0", "title": "Core Functionality", - "description": "APIs for managing your account balance. These endpoints are available with all Circle APIs." + "description": "All of Circle's APIs share a common set of core functionality that lets you manage your Circle Account in a programmatic way.\n\nWith a Circle Account your business can deposit traditional money from 80+ countries and seamlessly convert them into \"digital currency dollars\": USDC. You can then use USDC for everyday payments and treasury flows.\n" }, "tags": [ { - "name": "Balances" + "name": "Balances", + "description": "Get information on settled and unsettled balances." }, { - "name": "Payouts" + "name": "Payouts", + "description": "Create and get information on 1st party payouts." }, { - "name": "Wires" + "name": "Wires", + "description": "Create, get instructions, and get information on 1st party bank accounts for wire transfers." }, { - "name": "Signet" + "name": "Signet", + "description": "Create and get information on Signet accounts." }, { - "name": "SEN" + "name": "SEN", + "description": "Create and get information on SEN accounts." }, { - "name": "Transfers" + "name": "Transfers", + "description": "Create and get information on 1st party transfers." }, { - "name": "Addresses" + "name": "Addresses", + "description": "Generate and get information on blockchain addresses." }, { - "name": "Deposits" + "name": "Deposits", + "description": "Get information on 1st party deposits." } ], "paths": { @@ -98,6 +106,113 @@ } }, "/v1/businessAccount/payouts": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a payout", + "operationId": "createBusinessPayout", + "tags": [ + "Payouts" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BusinessPayoutCreationRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully created a payout.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreateBusinessPayoutResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/BusinessPayout" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "wire", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "name": "COMMERZBANK AG ****3000" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "trackingRef": "CIR-6ESOQANEP3NAO", + "errorCode": "insufficient_funds", + "riskEvaluation": { + "decision": "approved", + "reason": "3000" + }, + "adjustments": { + "fxCredit": { + "amount": "3.14", + "currency": "USD" + }, + "fxDebit": { + "amount": "3.14", + "currency": "USD" + } + }, + "return": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "reason": "payout_returned", + "status": "pending", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + }, "get": { "security": [ { @@ -127,6 +242,7 @@ "required": false, "schema": { "type": "array", + "uniqueItems": true, "items": { "$ref": "#/components/schemas/PayoutStatus" } @@ -241,113 +357,6 @@ "$ref": "#/components/responses/NotAuthorized" } } - }, - "post": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Create a payout", - "operationId": "createBusinessPayout", - "tags": [ - "Payouts" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BusinessPayoutCreationRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Successfully created a payout.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "CreateBusinessPayoutResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/BusinessPayout" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "sourceWalletId": "53535335", - "destination": { - "type": "wire", - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "name": "COMMERZBANK AG ****3000" - }, - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "status": "pending", - "trackingRef": "CIR-6ESOQANEP3NAO", - "errorCode": "insufficient_funds", - "riskEvaluation": { - "decision": "approved", - "reason": "3000" - }, - "adjustments": { - "fxCredit": { - "amount": "3.14", - "currency": "USD" - }, - "fxDebit": { - "amount": "3.14", - "currency": "USD" - } - }, - "return": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "reason": "payout_returned", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - }, - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - } - } } }, "/v1/businessAccount/payouts/{id}": { @@ -2059,13 +2068,14 @@ "format": "uuid", "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, - "PayoutDestinationType": { + "BusinessAccountPayoutDestinationType": { "type": "string", "description": "The destination bank account type.", "enum": [ "wire", "ach", - "sepa" + "sepa", + "signet" ] }, "BankDestination": { @@ -2077,7 +2087,7 @@ ], "properties": { "type": { - "$ref": "#/components/schemas/PayoutDestinationType" + "$ref": "#/components/schemas/BusinessAccountPayoutDestinationType" }, "id": { "$ref": "#/components/schemas/Id" @@ -2085,7 +2095,6 @@ "name": { "type": "string", "description": "Bank name plus last four digits of the bank account number or IBAN.", - "readOnly": true, "example": "COMMERZBANK AG ****3000" } } @@ -2301,7 +2310,8 @@ "type": "string", "enum": [ "wire", - "sen" + "sen", + "signet" ] }, "id": { @@ -3233,7 +3243,6 @@ }, "fees": { "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Fee" diff --git a/openapi/json/accounts.json b/openapi/json/accounts.json index a136b57..3c1426e 100644 --- a/openapi/json/accounts.json +++ b/openapi/json/accounts.json @@ -2,20 +2,22 @@ "openapi": "3.0.2", "servers": [ { - "url": "api-sandbox.circle.com" + "url": "https://api-sandbox.circle.com" } ], "info": { - "version": "1.0.3", + "version": "1.1.0", "title": "Accounts API", - "description": "APIs to manage custodial wallets." + "description": "The Accounts API allows you to easily create and host digital wallets for your customers, and manage transfers of funds across accounts- whether they are within the Circle platform, or in / out of the platform via on-chain USDC, EUROC, BTC, and ETH connectivity." }, "tags": [ { - "name": "Wallets" + "name": "Wallets", + "description": "Create digital wallets and get information on their activity." }, { - "name": "Transfers" + "name": "Transfers", + "description": "Create transfers to another wallet or blockchain address, and get information on those transfers." } ], "paths": { @@ -1351,7 +1353,6 @@ }, "fees": { "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Fee" @@ -1536,7 +1537,6 @@ }, "fees": { "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Fee" diff --git a/openapi/json/circle-apis.json b/openapi/json/circle-apis.json index 405a9d8..c7bfbbd 100644 --- a/openapi/json/circle-apis.json +++ b/openapi/json/circle-apis.json @@ -2,86 +2,122 @@ "openapi": "3.0.2", "servers": [ { - "url": "api-sandbox.circle.com" + "url": "https://api-sandbox.circle.com" } ], "info": { - "version": "1.0.3", + "version": "1.1.0", "title": "All Circle APIs", - "description": "Circle's General, Core Functionality, Payments, Payouts, and Accounts APIs bundled into one OpenAPI Specification." + "description": "Circle's General, Core Functionality, Payments, Payouts, Accounts, and Crypto Payments APIs bundled into one OpenAPI Specification." }, "tags": [ { - "name": "Health" + "name": "ACH", + "description": "Link and get information on bank account for ACH payments." }, { - "name": "Management" + "name": "Addresses", + "description": "Generate and get information on blockchain addresses." }, { - "name": "Encryption" + "name": "Crypto Address Book", + "description": "Manage blockchain addresses with metadata." }, { - "name": "Subscriptions" + "name": "Balances", + "description": "Get information on settled and unsettled balances." }, { - "name": "Stablecoins" + "name": "Cards", + "description": "Link, update, and get information on debit/credit cards." }, { - "name": "Channels" + "name": "Payment Tokens", + "description": "Create Apple Pay and Google Pay payment tokens." }, { - "name": "Balances" + "name": "Channels", + "description": "View a list of channels." }, { - "name": "Addresses" + "name": "Chargebacks", + "description": "Get information on card chargebacks." }, { - "name": "Cards" + "name": "Crypto Payment Intents", + "description": "Create and track intent for end user to pay via crypto." }, { - "name": "Wires" + "name": "Deposits", + "description": "Get information on 1st party deposits." }, { - "name": "SEN" + "name": "Encryption", + "description": "Encrypt sensitive data." }, { - "name": "SEPA" + "name": "Crypto Exchange Rates", + "description": "Pull estimated exchange rate for crypto currencies." }, { - "name": "ACH" + "name": "Health", + "description": "Inspect the health of the API." }, { - "name": "Signet" + "name": "Management", + "description": "General account and management information." }, { - "name": "Deposits" + "name": "Payments", + "description": "Get updates on whether user's crypto payment was received." }, { - "name": "Payment Intents" + "name": "Payouts", + "description": "Create and get information on wire, ACH, SEPA and address book payouts." }, { - "name": "Payments" + "name": "Returns", + "description": "Get information on returned payouts." }, { - "name": "Settlements" + "name": "Reversals", + "description": "Get information on ACH reversals." }, { - "name": "Chargebacks" + "name": "SEN", + "description": "Create and get information on SEN accounts." }, { - "name": "Reversals" + "name": "SEPA", + "description": "Create and get information on SEPA accounts." }, { - "name": "Payouts" + "name": "Settlements", + "description": "Get information on settlement batches." }, { - "name": "Returns" + "name": "Signet", + "description": "Create and get information on Signet accounts." }, { - "name": "Wallets" + "name": "Stablecoins", + "description": "Retrieve stablecoins and their respective names, symbols, circulating total and per-chain amounts." }, { - "name": "Transfers" + "name": "Subscriptions", + "description": "Manage subscriptions to notifications." + }, + { + "name": "Transfers", + "description": "Create transfers to another wallet or blockchain address, and get information on those transfers." + }, + { + "name": "Wallets", + "description": "Create digital wallets and get information on their activity." + }, + { + "name": "Wires", + "description": "Create, get instructions, and get information on bank accounts for wire transfers." } ], "paths": { @@ -210,122 +246,122 @@ } }, "/v1/notifications/subscriptions": { - "get": { + "post": { "security": [ { "bearerAuth": [] } ], - "summary": "List all notification subscriptions", - "description": "Retrieve a list of existing notification subscriptions with details.", - "parameters": [], - "operationId": "listSubscriptions", + "summary": "Create a notification subscription", + "description": "Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error.\n", + "operationId": "createSubscription", "tags": [ "Subscriptions" ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubscriptionRequest" + } + } + } + }, "responses": { "200": { - "description": "Successfully retrieved a list of notification subscriptions.", + "description": "Successfully created a notification subscription.", "content": { "application/json": { "schema": { - "title": "ListSubscriptionsResponse", + "title": "CreateSubscriptionResponse", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SubscriptionResponse" - } + "$ref": "#/components/schemas/SubscriptionResponse" } } }, "examples": { "response": { "value": { - "data": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "endpoint": "https://example.org/handler/for/notifications", - "subscriptionDetails": [ - { - "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", - "status": "confirmed" - } - ] - } - ] + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "endpoint": "https://example.org/handler/for/notifications", + "subscriptionDetails": [ + { + "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", + "status": "confirmed" + } + ] + } } } } } } }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, "401": { "$ref": "#/components/responses/NotAuthorized" + }, + "429": { + "$ref": "#/components/responses/LimitExceeded" } } }, - "post": { + "get": { "security": [ { "bearerAuth": [] } ], - "summary": "Create a notification subscription", - "description": "Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error.\n", - "operationId": "createSubscribtion", + "summary": "List all notification subscriptions", + "description": "Retrieve a list of existing notification subscriptions with details.", + "parameters": [], + "operationId": "listSubscriptions", "tags": [ "Subscriptions" ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SubscriptionRequest" - } - } - } - }, "responses": { "200": { - "description": "Successfully created a notification subscription.", + "description": "Successfully retrieved a list of notification subscriptions.", "content": { "application/json": { "schema": { - "title": "CreateSubscribtionResponse", + "title": "ListSubscriptionsResponse", "properties": { "data": { - "$ref": "#/components/schemas/SubscriptionResponse" + "type": "array", + "items": { + "$ref": "#/components/schemas/SubscriptionResponse" + } } } }, "examples": { "response": { "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "endpoint": "https://example.org/handler/for/notifications", - "subscriptionDetails": [ - { - "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", - "status": "confirmed" - } - ] - } + "data": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "endpoint": "https://example.org/handler/for/notifications", + "subscriptionDetails": [ + { + "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", + "status": "confirmed" + } + ] + } + ] } } } } } }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, "401": { "$ref": "#/components/responses/NotAuthorized" - }, - "429": { - "$ref": "#/components/responses/LimitExceeded" } } } @@ -344,7 +380,7 @@ ], "summary": "Remove a notification subscription", "description": "To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed.", - "operationId": "deleteSubscribtion", + "operationId": "deleteSubscription", "tags": [ "Subscriptions" ], @@ -359,7 +395,7 @@ "content": { "application/json": { "schema": { - "title": "DeleteSubscribtionResponse", + "title": "DeleteSubscriptionResponse", "properties": { "data": { "$ref": "#/components/schemas/UnsubscribeResponse" @@ -761,6 +797,7 @@ "network": "VISA", "bin": "401230", "issuerCountry": "US", + "fundingType": "credit", "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "verification": { "avs": "D", @@ -965,6 +1002,80 @@ } } }, + "/v1/paymentTokens": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a payment token", + "description": "Convert a digital wallet (Apple Pay, Google Pay) token to a single-use payment token.", + "operationId": "createPaymentToken", + "tags": [ + "Payment Tokens" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentTokenRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully converted a digital token to a Circle token account.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreatePaymentTokenResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/PaymentToken" + } + } + }, + "examples": { + "response": { + "value": { + "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" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + } + }, "/v1/businessAccount/banks/wires": { "post": { "security": [ @@ -2773,7 +2884,7 @@ "summary": "Create a payment intent", "operationId": "createPaymentIntent", "tags": [ - "Payment Intents" + "Crypto Payment Intents" ], "requestBody": { "content": { @@ -2858,7 +2969,7 @@ "summary": "List all payment intents", "operationId": "listPaymentIntents", "tags": [ - "Payment Intents" + "Crypto Payment Intents" ], "parameters": [ { @@ -2933,7 +3044,6 @@ "value": { "data": [ { - "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", "amount": { "amount": "3.14", @@ -2995,7 +3105,7 @@ "summary": "Get a payment intent", "operationId": "getPaymentIntent", "tags": [ - "Payment Intents" + "Crypto Payment Intents" ], "parameters": [ { @@ -3075,7 +3185,7 @@ "summary": "Expire a payment intent", "operationId": "expirePaymentIntent", "tags": [ - "Payment Intents" + "Crypto Payment Intents" ], "parameters": [ { @@ -3163,53 +3273,30 @@ } } }, - "/v1/payments": { - "get": { + "/v1/addressBook/recipients": { + "post": { "security": [ { "bearerAuth": [] } ], - "parameters": [ - { - "$ref": "#/components/parameters/Source" - }, - { - "$ref": "#/components/parameters/SettlementId" - }, - { - "$ref": "#/components/parameters/PaymentIntentId" - }, - { - "$ref": "#/components/parameters/PaymentSourceType" - }, - { - "$ref": "#/components/parameters/PaymentStatus" - }, - { - "$ref": "#/components/parameters/From" - }, - { - "$ref": "#/components/parameters/To" - }, - { - "$ref": "#/components/parameters/PageBefore" - }, - { - "$ref": "#/components/parameters/PageAfter" - }, - { - "$ref": "#/components/parameters/PageSize" - } - ], - "summary": "List all payments", - "operationId": "listPayments", + "summary": "Create a recipient", + "operationId": "createAddressBookRecipient", "tags": [ - "Payments" + "Crypto Address Book" ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressBookRecipientRequest" + } + } + } + }, "responses": { - "200": { - "description": "Successfully retrieved a list of payments.", + "201": { + "description": "Successfully created an address book recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -3218,49 +3305,642 @@ "content": { "application/json": { "schema": { - "title": "ListPaymentsResponse", + "title": "CreateAddressBookRecipientResponse", "properties": { "data": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/FiatPayment" - }, - { - "$ref": "#/components/schemas/CryptoPayment" - }, - { - "$ref": "#/components/schemas/FiatCancel" - }, - { - "$ref": "#/components/schemas/FiatRefund" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "Fiat Payment": "#/components/schemas/FiatPayment", - "Crypto Payment": "#/components/schemas/CryptoPayment", - "Fiat Cancel": "#/components/schemas/FiatCancel", - "Fiat Refund": "#/components/schemas/FiatRefund" - } - } - } + "$ref": "#/components/schemas/AddressBookRecipient" } } }, "examples": { - "Fiat Payment": { + "response": { "value": { - "data": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", + "data": { + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", + "chain": "ETH", + "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" + }, + "status": "pending", + "createDate": "2022-07-21T20:13:35.578678Z", + "updateDate": "2022-07-21T20:19:24.859052Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + }, + "get": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "List all recipients", + "operationId": "listAddressBookRecipients", + "tags": [ + "Crypto Address Book" + ], + "parameters": [ + { + "name": "address", + "description": "Filters results to fetch only address book recipients with the provided address.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "chain", + "description": "Filters results to fetch only address book recipients with the provided chain.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "email", + "description": "Filters results to fetch only address book recipients that have the provided email in their metadata.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "status", + "description": "Filters results to fetch only address book recipients that have the provided status.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "inactive", + "active", + "denied" + ] + } + }, + { + "$ref": "#/components/parameters/From" + }, + { + "$ref": "#/components/parameters/To" + }, + { + "$ref": "#/components/parameters/PageBefore" + }, + { + "$ref": "#/components/parameters/PageAfter" + }, + { + "$ref": "#/components/parameters/PageSize" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved a list of address book recipients.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "ListAddressBookRecipientsResponse", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AddressBookRecipient" + } + } + } + }, + "examples": { + "response": { + "value": { + "data": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "chain": "ALGO", + "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", + "addressTag": "123456789", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" + }, + "status": "pending", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + } + }, + "/v1/addressBook/recipients/{id}": { + "get": { + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get a recipient", + "operationId": "getAddressBookRecipient", + "tags": [ + "Crypto Address Book" + ], + "responses": { + "200": { + "description": "Successfully retrieved an address book recipient.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "GetAddressBookRecipientResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/AddressBookRecipient" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "chain": "ALGO", + "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", + "addressTag": "123456789", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" + }, + "status": "pending", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + }, + "patch": { + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Modify a recipient", + "operationId": "modifyAddressBookRecipient", + "tags": [ + "Crypto Address Book" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressBookRecipientModifyRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully updated the address book recipient.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "ModifyAddressBookRecipientResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/AddressBookRecipient" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", + "chain": "ETH", + "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" + }, + "status": "pending", + "createDate": "2022-07-21T20:13:35.578678Z", + "updateDate": "2022-07-21T20:19:24.859052Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + }, + "delete": { + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Delete a recipient", + "operationId": "deleteAddressBookRecipient", + "tags": [ + "Crypto Address Book" + ], + "responses": { + "200": { + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "description": "Successfully removed the address book recipient." + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/payments": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a payment", + "operationId": "createPayment", + "tags": [ + "Payments" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentCreationRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully created a payment.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreatePaymentResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/DetailedPayment" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "captured": false, + "captureAmount": { + "amount": "3.14", + "currency": "USD" + }, + "captureDate": "2020-04-10T02:13:30.000Z", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "verification": { + "avs": "D", + "cvv": "not_requested", + "threeDSecure": "pass", + "eci": "00" + }, + "cancel": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "cancel", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "originalPayment": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "description": "Payment", + "status": "pending", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "createDate": "2020-04-10T02:13:30.000Z" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + }, + "refunds": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "refund", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "originalPayment": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "description": "Payment", + "status": "pending", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "createDate": "2020-04-10T02:13:30.000Z" + }, + "cancel": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "cancel", + "description": "Payment", + "status": "pending", + "createDate": "2020-04-10T02:13:30.000Z" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + ], + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "trackingRef": "24910599141085313498894", + "errorCode": "payment_failed", + "metadata": { + "email": "satoshi@circle.com", + "phoneNumber": "+14155555555" + }, + "riskEvaluation": { + "decision": "approved", + "reason": "3000" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + }, + "get": { + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/Source" + }, + { + "$ref": "#/components/parameters/SettlementId" + }, + { + "$ref": "#/components/parameters/PaymentIntentId" + }, + { + "$ref": "#/components/parameters/PaymentSourceType" + }, + { + "$ref": "#/components/parameters/PaymentStatus" + }, + { + "$ref": "#/components/parameters/From" + }, + { + "$ref": "#/components/parameters/To" + }, + { + "$ref": "#/components/parameters/PageBefore" + }, + { + "$ref": "#/components/parameters/PageAfter" + }, + { + "$ref": "#/components/parameters/PageSize" + } + ], + "summary": "List all payments", + "operationId": "listPayments", + "tags": [ + "Payments" + ], + "responses": { + "200": { + "description": "Successfully retrieved a list of payments.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "ListPaymentsResponse", + "properties": { + "data": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/FiatPayment" + }, + { + "$ref": "#/components/schemas/CryptoPayment" + }, + { + "$ref": "#/components/schemas/FiatCancel" + }, + { + "$ref": "#/components/schemas/FiatRefund" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "Fiat Payment": "#/components/schemas/FiatPayment", + "Crypto Payment": "#/components/schemas/CryptoPayment", + "Fiat Cancel": "#/components/schemas/FiatCancel", + "Fiat Refund": "#/components/schemas/FiatRefund" + } + } + } + } + } + }, + "examples": { + "Fiat Payment": { + "value": { + "data": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", "currency": "USD" }, "source": { @@ -3390,241 +4070,41 @@ "id": "03fbe7da-096a-4763-af77-e43006cd83be", "type": "refund", "status": "paid", - "description": "Refund Payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "fees": { - "amount": "0.00", - "currency": "USD" - }, - "createDate": "2022-04-21T12:49:21.146Z", - "updateDate": "2022-04-21T12:54:10.596976Z", - "merchantId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b", - "merchantWalletId": "1000174786", - "source": { - "id": "45fa5524-41b9-48ca-94cd-f45cb36cce4d", - "type": "card" - }, - "originalPayment": { - "id": "895f8db5-1d8c-407d-9533-b5ca3fbcc74e", - "type": "payment", - "status": "paid", - "createDate": "2022-04-06T19:33:29.690Z", - "updateDate": "2022-04-06T19:47:23.681180Z" - }, - "reason": "requested_by_customer" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - } - } - }, - "post": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Create a payment", - "operationId": "createPayment", - "tags": [ - "Payments" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PaymentCreationRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Successfully created a payment.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "CreatePaymentResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/DetailedPayment" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "captured": false, - "captureAmount": { - "amount": "3.14", - "currency": "USD" - }, - "captureDate": "2020-04-10T02:13:30.000Z", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "verification": { - "avs": "D", - "cvv": "not_requested", - "threeDSecure": "pass", - "eci": "00" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", + "description": "Refund Payment", "amount": { "amount": "3.14", "currency": "USD" }, + "fees": { + "amount": "0.00", + "currency": "USD" + }, + "createDate": "2022-04-21T12:49:21.146Z", + "updateDate": "2022-04-21T12:54:10.596976Z", + "merchantId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b", + "merchantWalletId": "1000174786", "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "id": "45fa5524-41b9-48ca-94cd-f45cb36cce4d", "type": "card" }, - "description": "Payment", - "status": "pending", "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "id": "895f8db5-1d8c-407d-9533-b5ca3fbcc74e", "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, - "fees": { - "amount": "3.14", - "currency": "USD" + "status": "paid", + "createDate": "2022-04-06T19:33:29.690Z", + "updateDate": "2022-04-06T19:47:23.681180Z" }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - }, - "refunds": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "refund", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "description": "Payment", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - ], - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "trackingRef": "24910599141085313498894", - "errorCode": "payment_failed", - "metadata": { - "email": "satoshi@circle.com", - "phoneNumber": "+14155555555" - }, - "riskEvaluation": { - "decision": "approved", - "reason": "3000" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } + "reason": "requested_by_customer" + } + ] } } } } } }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, "401": { "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" } } } @@ -3671,7 +4151,7 @@ "discriminator": { "propertyName": "type", "mapping": { - "Fiat Payment": "#/components/schemas/FiatPayment", + "Fiat Payment": "#/components/schemas/FiatPaymentPolymorphic", "Crypto Payment": "#/components/schemas/CryptoPayment" } } @@ -4252,66 +4732,175 @@ "amount": "3.14", "currency": "USD" }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + }, + "cancel": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "cancel", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "originalPayment": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "description": "Payment", + "status": "pending", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "createDate": "2020-04-10T02:13:30.000Z" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "trackingRef": "24910599141085313498894", + "errorCode": "payment_failed", + "metadata": { + "email": "satoshi@circle.com", + "phoneNumber": "+14155555555" + }, + "riskEvaluation": { + "decision": "approved", + "reason": "3000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/businessAccount/payouts": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a payout", + "operationId": "createBusinessPayout", + "tags": [ + "Payouts" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BusinessPayoutCreationRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully created a payout.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreateBusinessPayoutResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/BusinessPayout" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "wire", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "name": "COMMERZBANK AG ****3000" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "trackingRef": "CIR-6ESOQANEP3NAO", + "errorCode": "insufficient_funds", + "riskEvaluation": { + "decision": "approved", + "reason": "3000" + }, + "adjustments": { + "fxCredit": { + "amount": "3.14", + "currency": "USD" + }, + "fxDebit": { + "amount": "3.14", + "currency": "USD" + } }, - "cancel": { + "return": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", + "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", "amount": { "amount": "3.14", "currency": "USD" }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, "fees": { "amount": "3.14", "currency": "USD" }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "reason": "payout_returned", + "status": "pending", "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "trackingRef": "24910599141085313498894", - "errorCode": "payment_failed", - "metadata": { - "email": "satoshi@circle.com", - "phoneNumber": "+14155555555" - }, - "riskEvaluation": { - "decision": "approved", - "reason": "3000" - }, "createDate": "2020-04-10T02:13:30.000Z", "updateDate": "2020-04-10T02:13:30.000Z" } @@ -4321,16 +4910,14 @@ } } }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, "401": { "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" } } - } - }, - "/v1/businessAccount/payouts": { + }, "get": { "security": [ { @@ -4360,6 +4947,7 @@ "required": false, "schema": { "type": "array", + "uniqueItems": true, "items": { "$ref": "#/components/schemas/PayoutStatus" } @@ -4474,113 +5062,6 @@ "$ref": "#/components/responses/NotAuthorized" } } - }, - "post": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Create a payout", - "operationId": "createBusinessPayout", - "tags": [ - "Payouts" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BusinessPayoutCreationRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Successfully created a payout.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "CreateBusinessPayoutResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/BusinessPayout" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "sourceWalletId": "53535335", - "destination": { - "type": "wire", - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "name": "COMMERZBANK AG ****3000" - }, - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "status": "pending", - "trackingRef": "CIR-6ESOQANEP3NAO", - "errorCode": "insufficient_funds", - "riskEvaluation": { - "decision": "approved", - "reason": "3000" - }, - "adjustments": { - "fxCredit": { - "amount": "3.14", - "currency": "USD" - }, - "fxDebit": { - "amount": "3.14", - "currency": "USD" - } - }, - "return": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "payoutId": "abdb500d-4a59-457c-801f-2d418c8703ac", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "reason": "payout_returned", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - }, - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - } - } } }, "/v1/businessAccount/payouts/{id}": { @@ -4689,75 +5170,37 @@ } }, "/v1/payouts": { - "get": { + "post": { "security": [ { "bearerAuth": [] } ], - "parameters": [ - { - "name": "source", - "description": "Universally unique identifier (UUID v4) for the source wallet. Filters the results to fetch all payouts made from a source wallet. If not provided, payouts from all wallets will be returned.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "uuid", - "example": "54c1cbab-c419-450f-ad23-906fa03af7f0" - } - }, - { - "name": "type", - "description": "Destination bank account type. Filters the results to fetch all payouts made to a specified destination bank account type. This query parameter can be passed multiple times to fetch results matching multiple destination bank account types.", - "in": "query", - "required": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PayoutDestinationType" - } - } - }, - { - "name": "status", - "description": "Queries items with the specified status. Matches any status if unspecified.", - "in": "query", - "required": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PayoutStatus" - } - } - }, - { - "$ref": "#/components/parameters/Destination" - }, - { - "$ref": "#/components/parameters/From" - }, - { - "$ref": "#/components/parameters/To" - }, - { - "$ref": "#/components/parameters/PageBefore" - }, - { - "$ref": "#/components/parameters/PageAfter" - }, - { - "$ref": "#/components/parameters/PageSize" - } - ], - "summary": "List all payouts", - "operationId": "listPayouts", + "summary": "Create a payout", + "description": "\nCreate a wire, ACH, SEPA or crypto payout. \n\nThe following table includes the supported pairs of amount.currency and toAmount.currency for address book payouts:\n\n| amount.currency | toAmount.currency |\n| ---------------- | ------------ |\n| USD | USD |\n| USD | BTC |\n| USD | ETH |\n| USD | MTC |\n| EUR | EUR |\n| BTC | USD |\n| BTC | BTC |\n| ETH | USD |\n| ETH | ETH |\n", + "operationId": "createPayout", "tags": [ "Payouts" ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/FiatPayoutCreationRequest" + }, + { + "$ref": "#/components/schemas/CryptoPayoutCreationRequest" + } + ] + } + } + } + }, "responses": { - "200": { - "description": "Successfully retrieved a list of payouts.", + "201": { + "description": "Successfully created a payout.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -4766,18 +5209,22 @@ "content": { "application/json": { "schema": { - "title": "ListPayoutsResponse", + "title": "CreatePayoutResponse", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Payout" - } + "oneOf": [ + { + "$ref": "#/components/schemas/FiatPayout" + }, + { + "$ref": "#/components/schemas/CryptoPayout" + } + ] } } }, "examples": { - "response": { + "Fiat Payout": { "value": { "data": [ { @@ -4792,6 +5239,10 @@ "amount": "3.14", "currency": "USD" }, + "toAmount": { + "amount": "3.14", + "currency": "EUR" + }, "fees": { "amount": "3.14", "currency": "USD" @@ -4834,39 +5285,168 @@ } ] } + }, + "Crypto Payout": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "address_book", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "toAmount": { + "amount": "3.14", + "currency": "ETH" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "errorCode": "transaction_denied", + "riskEvaluation": { + "decision": "denied", + "reason": "4000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } } } } } }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, - "post": { + "get": { "security": [ { "bearerAuth": [] } ], - "summary": "Create a payout", - "operationId": "createPayout", - "tags": [ - "Payouts" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PayoutCreationRequest" + "parameters": [ + { + "name": "source", + "description": "Identifier for the source wallet. Filters the fetched payout results to only be from a specific source wallet. If not provided, payouts from all wallets will be returned.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "example": "1000565227" + } + }, + { + "name": "destination", + "description": "Universally unique identifier (UUID v4) for the destination. Filters the fetched payout results made to a specific destination. If not provided, payouts to all destinations will be returned.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uuid", + "example": "54c1cbab-c419-450f-ad23-906fa03af7f0" + } + }, + { + "name": "type", + "description": "Destination type. Filters the results to fetch all payouts made to a specified destination type. This query parameter can be passed multiple times to fetch results matching multiple destination types. The address_book destination type cannot be combined with other types.", + "in": "query", + "required": false, + "schema": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/components/schemas/PayoutDestinationType" } } + }, + { + "name": "status", + "description": "Queries items with the specified status. Matches any status if unspecified.", + "in": "query", + "required": false, + "schema": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/components/schemas/PayoutStatus" + } + } + }, + { + "name": "sourceCurrency", + "description": "Queries items with the specified source currency `amount.currency`. Matches any source currency if unspecified.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC", + "FLW", + "MAN" + ] + } + }, + { + "name": "destinationCurrency", + "description": "Queries items with the specified destination currency `toAmount.currency`. Matches any destination currency if unspecified.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC", + "FLW", + "MAN" + ] + } + }, + { + "$ref": "#/components/parameters/Chain" + }, + { + "$ref": "#/components/parameters/From" + }, + { + "$ref": "#/components/parameters/To" + }, + { + "$ref": "#/components/parameters/PageBefore" + }, + { + "$ref": "#/components/parameters/PageAfter" + }, + { + "$ref": "#/components/parameters/PageSize" } - }, + ], + "summary": "List all payouts", + "operationId": "listPayouts", + "tags": [ + "Payouts" + ], "responses": { - "201": { - "description": "Successfully created a payout.", + "200": { + "description": "Successfully retrieved a list of payouts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -4875,15 +5455,25 @@ "content": { "application/json": { "schema": { - "title": "CreatePayoutResponse", + "title": "ListPayoutsResponse", "properties": { "data": { - "$ref": "#/components/schemas/Payout" + "type": "array", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/FiatPayout" + }, + { + "$ref": "#/components/schemas/CryptoPayout" + } + ] + } } } }, "examples": { - "response": { + "Fiat Payout": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", @@ -4897,6 +5487,10 @@ "amount": "3.14", "currency": "USD" }, + "toAmount": { + "amount": "3.14", + "currency": "EUR" + }, "fees": { "amount": "3.14", "currency": "USD" @@ -4938,14 +5532,45 @@ "updateDate": "2020-04-10T02:13:30.000Z" } } + }, + "Crypto Payout": { + "value": { + "data": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "address_book", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "toAmount": { + "amount": "3.14", + "currency": "ETH" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "errorCode": "transaction_denied", + "riskEvaluation": { + "decision": "denied", + "reason": "4000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + ] + } } } } } }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, "401": { "$ref": "#/components/responses/NotAuthorized" } @@ -4983,12 +5608,19 @@ "title": "GetPayoutResponse", "properties": { "data": { - "$ref": "#/components/schemas/DetailedPayout" + "oneOf": [ + { + "$ref": "#/components/schemas/FiatDetailedPayout" + }, + { + "$ref": "#/components/schemas/CryptoPayout" + } + ] } } }, "examples": { - "response": { + "Fiat Payout": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", @@ -5002,6 +5634,10 @@ "amount": "3.14", "currency": "USD" }, + "toAmount": { + "amount": "3.14", + "currency": "EUR" + }, "fees": { "amount": "3.14", "currency": "USD" @@ -5044,6 +5680,38 @@ "updateDate": "2020-04-10T02:13:30.000Z" } } + }, + "Crypto Payout": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "address_book", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "toAmount": { + "amount": "3.14", + "currency": "ETH" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "errorCode": "transaction_denied", + "riskEvaluation": { + "decision": "denied", + "reason": "4000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } } } } @@ -5145,6 +5813,75 @@ } } }, + "/v1/exchange/rates/{trading-pair}": { + "get": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get a exchange rate", + "description": "Fetch the current rates for the specified trading pair. The trading pair is defined by a base currency followed by a quote currency. The response contains buy and sell rates denominated in the quote currency. **Exchange rate is an estimate only and is subject to change by the time you submit the actual request.**", + "operationId": "getExchangeRates", + "tags": [ + "Crypto Exchange Rates" + ], + "parameters": [ + { + "name": "trading-pair", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "BTC-USD", + "ETH-USD", + "FLOW-USD" + ] + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved rates.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "GetExchangeRatesResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/Rate" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "buy": "46317.59000", + "sell": "45400.41000", + "createDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + } + }, "/v1/settlements": { "get": { "security": [ @@ -5374,6 +6111,7 @@ "paymentId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "reasonCode": "10.4", + "status": "active", "category": "Canceled Recurring Payment", "history": [ { @@ -5451,6 +6189,7 @@ "paymentId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "reasonCode": "10.4", + "status": "active", "category": "Canceled Recurring Payment", "history": [ { @@ -6826,7 +7565,7 @@ "content": { "application/json": { "schema": { - "title": "CreateAchAccountResponse", + "title": "CreateMockAchAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/MockAchAccountResponse" @@ -7419,6 +8158,16 @@ "description": "The country code of the issuer bank. Follows the ISO 3166-1 alpha-2 standard.", "example": "US" }, + "fundingType": { + "description": "The funding type of the card. Possible values are `credit`, `debit`, `prepaid`, and `unknown`.", + "type": "string", + "enum": [ + "credit", + "debit", + "prepaid", + "unknown" + ] + }, "fingerprint": { "$ref": "#/components/schemas/Fingerprint" }, @@ -7747,6 +8496,254 @@ } } }, + "ApplePayTokenEcHeader": { + "type": "object", + "required": [ + "ephemeralPublicKey", + "publicKeyHash", + "transactionId" + ], + "properties": { + "applicationData": { + "description": "Optional. Hash of the applicationData property of the original PKPaymentRequest object. If the value of that property is null, this key is omitted.", + "type": "string", + "example": "" + }, + "ephemeralPublicKey": { + "description": "Ephemeral public key bytes.", + "type": "string", + "example": "MFkwEwYHKoZIzj.../zlsw==" + }, + "publicKeyHash": { + "description": "Hash of the X.509 encoded public key bytes of the merchant’s certificate.", + "type": "string", + "example": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=" + }, + "transactionId": { + "description": "Transaction identifier, generated on the device.", + "type": "string", + "example": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4" + } + } + }, + "ApplePayTokenRsaHeader": { + "type": "object", + "required": [ + "wrappedKey", + "publicKeyHash", + "transactionId" + ], + "properties": { + "applicationData": { + "description": "Optional. Hash of the applicationData property of the original PKPaymentRequest object. If the value of that property is null, this key is omitted.", + "type": "string" + }, + "wrappedKey": { + "description": "The symmetric key wrapped using your RSA public key.", + "type": "string" + }, + "publicKeyHash": { + "description": "Hash of the X.509 encoded public key bytes of the merchant’s certificate.", + "type": "string" + }, + "transactionId": { + "description": "Transaction identifier, generated on the device.", + "type": "string" + } + } + }, + "ApplePayToken": { + "type": "object", + "required": [ + "version", + "data", + "signature", + "header" + ], + "properties": { + "version": { + "description": "ApplePay token version information.", + "type": "string", + "enum": [ + "EC_v1", + "RSA_v1" + ] + }, + "data": { + "description": "Encrypted payment data. Base64 encoded as a string.", + "type": "string", + "example": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+...T6Ms7PhiNZpuGEE2QE=" + }, + "signature": { + "description": "Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.", + "type": "string", + "example": "MIAGCSqGSIb3DQEHAqCAMIACAQEx.../WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=" + }, + "header": { + "description": "Additional version-dependent information used to decrypt and verify the payment.", + "oneOf": [ + { + "$ref": "#/components/schemas/ApplePayTokenEcHeader" + }, + { + "$ref": "#/components/schemas/ApplePayTokenRsaHeader" + } + ] + } + } + }, + "GooglePayToken": { + "type": "object", + "required": [ + "signature", + "protocolVersion", + "signedMessage" + ], + "properties": { + "signature": { + "description": "Verifies the message came from Google. The signature is created using ECDSA.", + "type": "string" + }, + "protocolVersion": { + "description": "Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0.", + "type": "string" + }, + "signedMessage": { + "description": "A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process, this value is serialized.", + "type": "string" + } + } + }, + "PaymentTokenRequest": { + "type": "object", + "required": [ + "idempotencyKey", + "type", + "tokenData" + ], + "properties": { + "idempotencyKey": { + "$ref": "#/components/schemas/IdempotencyKey" + }, + "type": { + "description": "Type of the digital wallet token.", + "type": "string", + "enum": [ + "applepay", + "googlepay" + ] + }, + "tokenData": { + "description": "The token data", + "oneOf": [ + { + "$ref": "#/components/schemas/ApplePayToken" + }, + { + "$ref": "#/components/schemas/GooglePayToken" + } + ] + } + } + }, + "TokenizedCardDetails": { + "type": "object", + "required": [ + "expMonth", + "expYear", + "last4", + "bin" + ], + "properties": { + "expMonth": { + "description": "The card's expiration month.", + "type": "integer", + "example": 1 + }, + "expYear": { + "description": "Four digit number representing the card's expiration year.", + "type": "integer", + "example": 2020 + }, + "network": { + "description": "The network of the card.", + "type": "string", + "enum": [ + "VISA", + "MASTERCARD", + "AMEX", + "UNKNOWN" + ] + }, + "last4": { + "description": "The last 4 digits of the card.", + "type": "string", + "example": "0123" + }, + "bin": { + "description": "The bank identification number (BIN), the first 6 digits of the card.", + "type": "string", + "example": "401230" + }, + "fundingType": { + "description": "The funding type of the card.", + "type": "string", + "enum": [ + "credit", + "debit", + "prepaid", + "unknown" + ] + }, + "issuerCountry": { + "description": "The country code of the issuer bank. Follows the ISO 3166-1 alpha-2 standard.", + "type": "string", + "example": "US" + } + } + }, + "PaymentToken": { + "type": "object", + "required": [ + "id", + "type", + "expiresOn", + "cardDetails", + "createDate", + "updateDate" + ], + "properties": { + "id": { + "description": "Unique system generated identifier for the digital wallet token.", + "type": "string", + "format": "uuid", + "example": "gc988ed5-c189-4f70-a074-e5beb7eb8e32" + }, + "type": { + "description": "Type of the digital wallet token.", + "type": "string", + "enum": [ + "applepay", + "googlepay" + ] + }, + "expiresOn": { + "description": "Datetime when the digital token expires. ISO-8601.", + "type": "string", + "format": "date-time", + "example": "2022-01-18T19:20:00Z" + }, + "cardDetails": { + "$ref": "#/components/schemas/TokenizedCardDetails" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, "BankAddress": { "type": "object", "description": "The address details for the bank, as provided during bank account creation.", @@ -8859,14 +9856,12 @@ }, "address": { "type": "string", - "readOnly": true, "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" } } }, "PaymentIntentFees": { "type": "object", - "readOnly": true, "required": [ "type", "amount", @@ -8896,7 +9891,6 @@ }, "Timeline": { "type": "object", - "readOnly": true, "required": [ "status", "time" @@ -8927,12 +9921,6 @@ } } }, - "UtcTimestampReadOnly": { - "type": "string", - "readOnly": true, - "description": "ISO-8601 UTC date/time format.", - "example": "2020-04-10T02:13:30.000Z" - }, "PaymentIntent": { "type": "object", "required": [ @@ -8942,12 +9930,8 @@ "paymentMethods" ], "properties": { - "idempotencyKey": { - "$ref": "#/components/schemas/IdempotencyKey" - }, "id": { "type": "string", - "readOnly": true, "description": "Unique system generated identifier for the entity.", "format": "uuid", "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" @@ -8958,7 +9942,6 @@ "amountPaid": { "description": "Sum of the the amount paid.", "type": "object", - "readOnly": true, "required": [ "amount", "currency" @@ -8978,54 +9961,144 @@ } } }, - "settlementCurrency": { - "description": "Desired currency for the payments to settle in.", + "settlementCurrency": { + "description": "Desired currency for the payments to settle in.", + "type": "string", + "enum": [ + "USD", + "BTC", + "ETH" + ] + }, + "paymentMethods": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentMethodBlockchain" + } + }, + "fees": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentIntentFees" + } + }, + "paymentIds": { + "description": "List of associated payments.", + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "example": "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" + } + }, + "timeline": { + "description": "State management timeline.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Timeline" + } + }, + "expiresOn": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, + "AddressBookRecipientMetadata": { + "type": "object", + "properties": { + "nickname": { + "type": "string", + "description": "Nickname related to the address.", + "example": "sample nickname" + }, + "email": { + "$ref": "#/components/schemas/Email" + }, + "bns": { + "type": "string", + "description": "Blockchain Name Service (e.g. ENS) domain for the address.", + "example": "sample.circle" + } + } + }, + "AddressBookRecipient": { + "type": "object", + "required": [ + "chain", + "address", + "metadata" + ], + "properties": { + "id": { + "$ref": "#/components/schemas/Id" + }, + "chain": { + "$ref": "#/components/schemas/Chain" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "addressTag": { + "$ref": "#/components/schemas/AddressTag" + }, + "metadata": { + "$ref": "#/components/schemas/AddressBookRecipientMetadata" + }, + "status": { "type": "string", + "description": "Status of the address book recipient.", "enum": [ - "USD", - "BTC", - "ETH" + "pending", + "inactive", + "active", + "denied" ] }, - "paymentMethods": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentMethodBlockchain" - } - }, - "fees": { - "type": "array", - "readOnly": true, - "items": { - "$ref": "#/components/schemas/PaymentIntentFees" - } + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" }, - "paymentIds": { - "description": "List of associated payments.", - "type": "array", - "readOnly": true, - "items": { - "type": "string", - "format": "uuid", - "example": "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" - } + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, + "AddressBookRecipientRequest": { + "type": "object", + "required": [ + "idempotencyKey", + "chain", + "address", + "metadata" + ], + "properties": { + "idempotencyKey": { + "$ref": "#/components/schemas/IdempotencyKey" }, - "timeline": { - "description": "State management timeline.", - "type": "array", - "readOnly": true, - "items": { - "$ref": "#/components/schemas/Timeline" - } + "chain": { + "$ref": "#/components/schemas/Chain" }, - "expiresOn": { - "$ref": "#/components/schemas/UtcTimestampReadOnly" + "address": { + "$ref": "#/components/schemas/Address" }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestampReadOnly" + "addressTag": { + "$ref": "#/components/schemas/AddressTag" }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestampReadOnly" + "metadata": { + "$ref": "#/components/schemas/AddressBookRecipientMetadata" + } + } + }, + "AddressBookRecipientModifyRequest": { + "type": "object", + "properties": { + "metadata": { + "$ref": "#/components/schemas/AddressBookRecipientMetadata" } } }, @@ -10044,45 +11117,249 @@ "metadata": { "$ref": "#/components/schemas/MetadataPhoneEmail" }, - "riskEvaluation": { - "$ref": "#/components/schemas/RiskEvaluation" + "riskEvaluation": { + "$ref": "#/components/schemas/RiskEvaluation" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, + "PayoutStatus": { + "type": "string", + "description": "Status of the payout. Status `pending` indicates that the payout is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", + "enum": [ + "pending", + "complete", + "failed" + ] + }, + "BusinessAccountPayoutDestinationType": { + "type": "string", + "description": "The destination bank account type.", + "enum": [ + "wire", + "ach", + "sepa", + "signet" + ] + }, + "BankDestination": { + "type": "object", + "description": "The destination bank account.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/BusinessAccountPayoutDestinationType" + }, + "id": { + "$ref": "#/components/schemas/Id" + }, + "name": { + "type": "string", + "description": "Bank name plus last four digits of the bank account number or IBAN.", + "example": "COMMERZBANK AG ****3000" + } + } + }, + "PayoutErrorCode": { + "type": "string", + "nullable": true, + "description": "Indicates the failure reason of a payout. Only present for payouts in failed state. Possible values are [`insufficient_funds`, `transaction_denied`, `transaction_failed`, `transaction_returned`, `bank_transaction_error`, `fiat_account_limit_exceeded`, `invalid_bank_account_number`, `invalid_ach_rtn`, `invalid_wire_rtn`, `vendor_inactive`]'", + "enum": [ + "insufficient_funds", + "transaction_denied", + "transaction_failed", + "transaction_returned", + "bank_transaction_error", + "fiat_account_limit_exceeded", + "invalid_bank_account_number", + "invalid_ach_rtn", + "invalid_wire_rtn", + "vendor_inactive" + ] + }, + "FinalAdjustments": { + "type": "object", + "description": "Final adjustment which increases (credits) or decreases (debits) the total returned amount to the source wallet.", + "nullable": true, + "properties": { + "fxCredit": { + "$ref": "#/components/schemas/FiatMoneyUsd" + }, + "fxDebit": { + "$ref": "#/components/schemas/FiatMoneyUsd" + } + } + }, + "IdPayout": { + "type": "string", + "description": "Universally unique identifier (UUID v4) of the payout that is associated with the return.", + "format": "uuid", + "example": "abdb500d-4a59-457c-801f-2d418c8703ac" + }, + "UnwithdrawalObject": { + "type": "object", + "description": "Return information if the payout is returned by bank. Only present if `errorCode` of payout is `transaction_returned`.", + "nullable": true, + "properties": { + "id": { + "$ref": "#/components/schemas/Id" + }, + "payoutId": { + "$ref": "#/components/schemas/IdPayout" + }, + "amount": { + "$ref": "#/components/schemas/FiatMoneyUsd" + }, + "fees": { + "$ref": "#/components/schemas/FiatMoneyUsd" + }, + "reason": { + "type": "string", + "description": "Reason for the return.", + "example": "payout_returned" + }, + "status": { + "type": "string", + "description": "Status of the return. A `pending` status indicates that the return is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", + "enum": [ + "pending", + "complete", + "failed" + ] + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, + "BusinessPayout": { + "type": "object", + "properties": { + "id": { + "$ref": "#/components/schemas/Id" + }, + "sourceWalletId": { + "type": "string", + "description": "The identifier of the source wallet used to fund a payout.", + "example": "53535335" + }, + "destination": { + "$ref": "#/components/schemas/BankDestination" + }, + "amount": { + "$ref": "#/components/schemas/FiatMoney" + }, + "fees": { + "$ref": "#/components/schemas/FiatMoneyUsd" + }, + "status": { + "$ref": "#/components/schemas/PayoutStatus" + }, + "trackingRef": { + "description": "A payout tracking reference. Will be present once known.", + "nullable": true, + "example": "CIR-6ESOQANEP3NAO" + }, + "errorCode": { + "$ref": "#/components/schemas/PayoutErrorCode" + }, + "riskEvaluation": { + "$ref": "#/components/schemas/RiskEvaluation" + }, + "adjustments": { + "$ref": "#/components/schemas/FinalAdjustments" + }, + "return": { + "$ref": "#/components/schemas/UnwithdrawalObject" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, + "BusinessDestinationRequest": { + "type": "object", + "description": "The destination bank account.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "wire", + "sen", + "signet" + ] + }, + "id": { + "$ref": "#/components/schemas/Id" + } + } + }, + "BusinessPayoutCreationRequest": { + "type": "object", + "required": [ + "idempotencyKey", + "destination", + "amount" + ], + "properties": { + "idempotencyKey": { + "$ref": "#/components/schemas/IdempotencyKey" }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" + "destination": { + "$ref": "#/components/schemas/BusinessDestinationRequest" }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" + "amount": { + "$ref": "#/components/schemas/FiatMoney" } } }, - "PayoutStatus": { + "PayoutDestinationType": { "type": "string", - "description": "Status of the payout. Status `pending` indicates that the payout is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", + "description": "The destination type.", "enum": [ - "pending", - "complete", - "failed" + "wire", + "ach", + "sepa", + "address_book" ] }, - "PayoutDestinationType": { + "FiatPayoutDestinationType": { "type": "string", - "description": "The destination bank account type.", + "description": "The destination type.", "enum": [ "wire", "ach", "sepa" ] }, - "BankDestination": { + "FiatPayoutDestination": { "type": "object", - "description": "The destination bank account.", + "description": "The destination.", "required": [ "type", "id" ], "properties": { "type": { - "$ref": "#/components/schemas/PayoutDestinationType" + "$ref": "#/components/schemas/FiatPayoutDestinationType" }, "id": { "$ref": "#/components/schemas/Id" @@ -10090,77 +11367,79 @@ "name": { "type": "string", "description": "Bank name plus last four digits of the bank account number or IBAN.", - "readOnly": true, "example": "COMMERZBANK AG ****3000" } } }, - "PayoutErrorCode": { - "type": "string", - "nullable": true, - "description": "Indicates the failure reason of a payout. Only present for payouts in failed state. Possible values are [`insufficient_funds`, `transaction_denied`, `transaction_failed`, `transaction_returned`, `bank_transaction_error`, `fiat_account_limit_exceeded`, `invalid_bank_account_number`, `invalid_ach_rtn`, `invalid_wire_rtn`, `vendor_inactive`]'", - "enum": [ - "insufficient_funds", - "transaction_denied", - "transaction_failed", - "transaction_returned", - "bank_transaction_error", - "fiat_account_limit_exceeded", - "invalid_bank_account_number", - "invalid_ach_rtn", - "invalid_wire_rtn", - "vendor_inactive" - ] - }, - "FinalAdjustments": { + "PayoutMoney": { "type": "object", - "description": "Final adjustment which increases (credits) or decreases (debits) the total returned amount to the source wallet.", - "nullable": true, + "required": [ + "amount", + "currency" + ], "properties": { - "fxCredit": { - "$ref": "#/components/schemas/FiatMoneyUsd" + "amount": { + "type": "string", + "description": "Magnitude of the amount, in units of the currency, with a `.`.", + "example": "3.14" }, - "fxDebit": { - "$ref": "#/components/schemas/FiatMoneyUsd" + "currency": { + "type": "string", + "description": "Currency code for the amount.", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC", + "FLW", + "MAN" + ] } } }, - "IdPayout": { - "type": "string", - "description": "Universally unique identifier (UUID v4) of the payout that is associated with the return.", - "format": "uuid", - "example": "abdb500d-4a59-457c-801f-2d418c8703ac" - }, - "UnwithdrawalObject": { + "FiatPayout": { "type": "object", - "description": "Return information if the payout is returned by bank. Only present if `errorCode` of payout is `transaction_returned`.", - "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/Id" }, - "payoutId": { - "$ref": "#/components/schemas/IdPayout" + "sourceWalletId": { + "type": "string", + "description": "The identifier of the source wallet used to fund a payout.", + "example": "53535335" + }, + "destination": { + "$ref": "#/components/schemas/FiatPayoutDestination" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, + "toAmount": { + "$ref": "#/components/schemas/PayoutMoney" + }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, - "reason": { - "type": "string", - "description": "Reason for the return.", - "example": "payout_returned" - }, "status": { - "type": "string", - "description": "Status of the return. A `pending` status indicates that the return is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", - "enum": [ - "pending", - "complete", - "failed" - ] + "$ref": "#/components/schemas/PayoutStatus" + }, + "trackingRef": { + "description": "A payout tracking reference. Will be present once known.", + "nullable": true, + "example": "CIR-6ESOQANEP3NAO" + }, + "errorCode": { + "$ref": "#/components/schemas/PayoutErrorCode" + }, + "riskEvaluation": { + "$ref": "#/components/schemas/RiskEvaluation" + }, + "adjustments": { + "$ref": "#/components/schemas/FinalAdjustments" + }, + "return": { + "$ref": "#/components/schemas/UnwithdrawalObject" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" @@ -10170,7 +11449,30 @@ } } }, - "BusinessPayout": { + "CryptoPayoutDestinationType": { + "type": "string", + "description": "The destination type.", + "enum": [ + "address_book" + ] + }, + "CryptoPayoutDestination": { + "type": "object", + "description": "The destination.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/CryptoPayoutDestinationType" + }, + "id": { + "$ref": "#/components/schemas/Id" + } + } + }, + "CryptoPayout": { "type": "object", "properties": { "id": { @@ -10182,34 +11484,26 @@ "example": "53535335" }, "destination": { - "$ref": "#/components/schemas/BankDestination" + "$ref": "#/components/schemas/CryptoPayoutDestination" }, "amount": { - "$ref": "#/components/schemas/FiatMoney" + "$ref": "#/components/schemas/PayoutMoney" + }, + "toAmount": { + "$ref": "#/components/schemas/PayoutMoney" }, "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" + "$ref": "#/components/schemas/PayoutMoney" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, - "trackingRef": { - "description": "A payout tracking reference. Will be present once known.", - "nullable": true, - "example": "CIR-6ESOQANEP3NAO" - }, "errorCode": { "$ref": "#/components/schemas/PayoutErrorCode" }, "riskEvaluation": { "$ref": "#/components/schemas/RiskEvaluation" }, - "adjustments": { - "$ref": "#/components/schemas/FinalAdjustments" - }, - "return": { - "$ref": "#/components/schemas/UnwithdrawalObject" - }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" }, @@ -10218,132 +11512,208 @@ } } }, - "BusinessDestinationRequest": { + "MetadataPayout": { "type": "object", - "description": "The destination bank account.", + "description": "Additional properties related to the payout beneficiary.", + "required": [ + "beneficiaryEmail" + ], + "properties": { + "beneficiaryEmail": { + "$ref": "#/components/schemas/Email" + } + } + }, + "FiatPayoutCreationRequest": { + "type": "object", + "required": [ + "idempotencyKey", + "destination", + "amount", + "metadata" + ], + "properties": { + "idempotencyKey": { + "$ref": "#/components/schemas/IdempotencyKey" + }, + "source": { + "$ref": "#/components/schemas/WalletLocation" + }, + "destination": { + "type": "object", + "description": "The destination.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/FiatPayoutDestinationType" + }, + "id": { + "$ref": "#/components/schemas/Id" + } + } + }, + "amount": { + "$ref": "#/components/schemas/FiatMoneyUsd" + }, + "metadata": { + "$ref": "#/components/schemas/MetadataPayout" + } + } + }, + "IdentityAddress": { + "type": "object", + "required": [ + "line1", + "city", + "district", + "postalCode", + "country" + ], + "properties": { + "line1": { + "type": "string", + "description": "Line one of the street address.", + "maxLength": 1024, + "example": "100 Money Street" + }, + "line2": { + "type": "string", + "description": "Line two of the street address.", + "maxLength": 1024, + "example": "Suite 1" + }, + "city": { + "type": "string", + "description": "City portion of the address.", + "maxLength": 1024, + "example": "Boston" + }, + "district": { + "description": "State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.", + "type": "string", + "maxLength": 16, + "example": "MA" + }, + "postalCode": { + "type": "string", + "description": "Postal / ZIP code of the address.", + "maxLength": 16, + "example": "01234" + }, + "country": { + "type": "string", + "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", + "maxLength": 2, + "example": "US" + } + } + }, + "Identity": { + "type": "object", + "description": "The identity of the originator. Identities are required when:\n * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n * `amount.amount` >= $3,000 in value\n", "required": [ "type", - "id" + "name", + "addresses" ], "properties": { "type": { "type": "string", + "description": "The type of identity for the originator.\n* `individual` - A uniquely distinguishable individual.\n* `business` - Any entity other than a natural person that can establish a permanent customer relationship with an affected entity or otherwise own property. This can include companies, foundations, anstalt, partnerships, associations and other relevantly similar entities.\n", "enum": [ - "wire", - "sen" + "individual", + "business" ] }, - "id": { - "$ref": "#/components/schemas/Id" + "name": { + "type": "string", + "description": "Full name of the identity.", + "example": "Satoshi Nakamoto", + "maxLength": 1024 + }, + "addresses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityAddress" + } } } }, - "BusinessPayoutCreationRequest": { + "TransferSourceWalletLocation": { + "description": "A source wallet location.", "type": "object", "required": [ - "idempotencyKey", - "destination", - "amount" + "type", + "id" ], "properties": { - "idempotencyKey": { - "$ref": "#/components/schemas/IdempotencyKey" - }, - "destination": { - "$ref": "#/components/schemas/BusinessDestinationRequest" + "type": { + "type": "string", + "enum": [ + "wallet" + ] }, - "amount": { - "$ref": "#/components/schemas/FiatMoney" - } - } - }, - "Payout": { - "type": "object", - "properties": { "id": { - "$ref": "#/components/schemas/Id" - }, - "sourceWalletId": { "type": "string", - "description": "The identifier of the source wallet used to fund a payout.", - "example": "53535335" - }, - "destination": { - "$ref": "#/components/schemas/BankDestination" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "status": { - "$ref": "#/components/schemas/PayoutStatus" - }, - "trackingRef": { - "description": "A payout tracking reference. Will be present once known.", - "nullable": true, - "example": "CIR-6ESOQANEP3NAO" - }, - "errorCode": { - "$ref": "#/components/schemas/PayoutErrorCode" - }, - "riskEvaluation": { - "$ref": "#/components/schemas/RiskEvaluation" - }, - "adjustments": { - "$ref": "#/components/schemas/FinalAdjustments" - }, - "return": { - "$ref": "#/components/schemas/UnwithdrawalObject" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" + "description": "The id of the wallet.", + "example": "12345" }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" + "identities": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Identity" + } } } }, - "MetadataPayout": { + "ToAmount": { "type": "object", - "description": "Additional properties related to the payout beneficiary.", "required": [ - "beneficiaryEmail" + "currency" ], "properties": { - "beneficiaryEmail": { - "$ref": "#/components/schemas/Email" + "currency": { + "type": "string", + "description": "Currency code for the amount.", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC" + ] } } }, - "PayoutCreationRequest": { + "CryptoPayoutCreationRequest": { "type": "object", "required": [ "idempotencyKey", "destination", - "amount", - "metadata" + "amount" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, "source": { - "$ref": "#/components/schemas/WalletLocation" + "$ref": "#/components/schemas/TransferSourceWalletLocation" }, "destination": { - "$ref": "#/components/schemas/BankDestination" + "$ref": "#/components/schemas/CryptoPayoutDestination" }, "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" + "$ref": "#/components/schemas/Money" }, - "metadata": { - "$ref": "#/components/schemas/MetadataPayout" + "toAmount": { + "$ref": "#/components/schemas/ToAmount" } } }, - "DetailedPayout": { + "FiatDetailedPayout": { "type": "object", "properties": { "id": { @@ -10355,11 +11725,14 @@ "example": "53535335" }, "destination": { - "$ref": "#/components/schemas/BankDestination" + "$ref": "#/components/schemas/FiatPayoutDestination" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, + "toAmount": { + "$ref": "#/components/schemas/PayoutMoney" + }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, @@ -10400,6 +11773,29 @@ } } }, + "Rate": { + "type": "object", + "required": [ + "buy", + "sell", + "createDate" + ], + "properties": { + "buy": { + "type": "string", + "description": "The buy rate denominated in the quote currency of the trading pair.", + "example": "46317.59000" + }, + "sell": { + "type": "string", + "description": "The sell rate denominated in the quote currency of the trading pair.", + "example": "45400.41000" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, "Settlement": { "type": "object", "properties": { @@ -10440,6 +11836,19 @@ "format": "uuid", "example": "fc988ed5-c129-4f70-a064-e5beb7eb8e32" }, + "ChargebackStatus": { + "type": "string", + "enum": [ + "active", + "resolved", + "pending", + "won", + "lost", + "canceled", + "closed" + ], + "description": "Enumerated status of the chargeback. `active` means you’ve received a dispute and you need to submit evidence if you want to defend against it. 'resolved' means the disputed payment had been refunded previously. Your account has not been debited. `pending` means we have acknowledged your evidence and forwarded it to the card issuer. `won` means you have won the dispute and your account has been credited. `lost` means the issuing bank has rejected your evidence and you have lost the dispute. There are no further financial implications. `canceled` means the issuing bank has canceled the dispute and your account has been credited. `closed` means the time to respond to this dispute has run out. No evidence can be submitted at this point." + }, "ChargebackCategories": { "type": "string", "description": "Enumerated category of the chargeback status codes based on the chargeback status code.", @@ -10503,6 +11912,7 @@ "id", "paymentId", "merchantId", + "status", "history", "reasonCode" ], @@ -10521,6 +11931,9 @@ "type": "string", "example": "10.4" }, + "status": { + "$ref": "#/components/schemas/ChargebackStatus" + }, "category": { "$ref": "#/components/schemas/ChargebackCategories" }, @@ -10650,112 +12063,6 @@ } } }, - "IdentityAddress": { - "type": "object", - "required": [ - "line1", - "city", - "district", - "postalCode", - "country" - ], - "properties": { - "line1": { - "type": "string", - "description": "Line one of the street address.", - "maxLength": 1024, - "example": "100 Money Street" - }, - "line2": { - "type": "string", - "description": "Line two of the street address.", - "maxLength": 1024, - "example": "Suite 1" - }, - "city": { - "type": "string", - "description": "City portion of the address.", - "maxLength": 1024, - "example": "Boston" - }, - "district": { - "description": "State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.", - "type": "string", - "maxLength": 16, - "example": "MA" - }, - "postalCode": { - "type": "string", - "description": "Postal / ZIP code of the address.", - "maxLength": 16, - "example": "01234" - }, - "country": { - "type": "string", - "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", - "maxLength": 2, - "example": "US" - } - } - }, - "Identity": { - "type": "object", - "description": "The identity of the originator. Identities are required when:\n * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n * `amount.amount` >= $3,000 in value\n", - "required": [ - "type", - "name", - "addresses" - ], - "properties": { - "type": { - "type": "string", - "description": "The type of identity for the originator.\n* `individual` - A uniquely distinguishable individual.\n* `business` - Any entity other than a natural person that can establish a permanent customer relationship with an affected entity or otherwise own property. This can include companies, foundations, anstalt, partnerships, associations and other relevantly similar entities.\n", - "enum": [ - "individual", - "business" - ] - }, - "name": { - "type": "string", - "description": "Full name of the identity.", - "example": "Satoshi Nakamoto", - "maxLength": 1024 - }, - "addresses": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentityAddress" - } - } - } - }, - "TransferSourceWalletLocation": { - "description": "A source wallet location.", - "type": "object", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "wallet" - ] - }, - "id": { - "type": "string", - "description": "The id of the wallet.", - "example": "12345" - }, - "identities": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Identity" - } - } - } - }, "TransferSourceBlockchainLocation": { "description": "A source blockchain address.", "type": "object", @@ -10929,7 +12236,6 @@ }, "fees": { "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Fee" @@ -11107,7 +12413,6 @@ }, "fees": { "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Fee" @@ -11708,6 +13013,7 @@ "required": false, "schema": { "type": "array", + "uniqueItems": true, "items": { "type": "string", "enum": [ @@ -11746,6 +13052,27 @@ "example": "e3d0a838-d732-49d0-bf44-73a668e38973" } }, + "Chain": { + "name": "chain", + "description": "Queries items with the specified chain. Matches any chain if unspecified", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ALGO", + "AVAX", + "BTC", + "ETH", + "FLOW", + "HBAR", + "MATIC", + "SOL", + "TRX", + "XLM" + ] + } + }, "PaymentId": { "name": "paymentId", "description": "The payment ID associated with the chargeback.", diff --git a/openapi/json/crypto-payments.json b/openapi/json/crypto-payments.json deleted file mode 100644 index 121fd0b..0000000 --- a/openapi/json/crypto-payments.json +++ /dev/null @@ -1,2208 +0,0 @@ -{ - "openapi": "3.0.2", - "servers": [ - { - "url": "api-sandbox.circle.com" - } - ], - "info": { - "version": "1.0.3", - "title": "Crypto Payments API", - "description": "Crypto Payments collection Circle APIs." - }, - "tags": [ - { - "name": "Payment Intents" - }, - { - "name": "Payments" - } - ], - "paths": { - "/v1/paymentIntents": { - "post": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Create a payment intent", - "operationId": "createPaymentIntent", - "tags": [ - "Payment Intents" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PaymentIntent" - } - } - } - }, - "responses": { - "201": { - "description": "Successfully created a payment intent.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "CreatePaymentIntentResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/PaymentIntent" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "8755d0ea-14f9-4259-b092-de23c14b6568", - "amount": { - "amount": "3.14", - "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" - } - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - } - } - }, - "get": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "List all payment intents", - "operationId": "listPaymentIntents", - "tags": [ - "Payment Intents" - ], - "parameters": [ - { - "name": "status", - "description": "Filters by the most recent `timeline.status` within the payment intent.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "created", - "pending", - "complete", - "expired", - "failed" - ] - } - }, - { - "name": "context", - "description": "Filters by the most recent `timeline.context` within the payment intent.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "underpaid", - "paid", - "overpaid" - ] - } - }, - { - "$ref": "#/components/parameters/From" - }, - { - "$ref": "#/components/parameters/To" - }, - { - "$ref": "#/components/parameters/PageBefore" - }, - { - "$ref": "#/components/parameters/PageAfter" - }, - { - "$ref": "#/components/parameters/PageSize" - } - ], - "responses": { - "200": { - "description": "Successfully retrieved a list of payment intents.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "ListPaymentIntentsResponse", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentIntent" - } - } - } - }, - "examples": { - "response": { - "value": { - "data": [ - { - "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "amountPaid": { - "amount": "3.14", - "currency": "USD" - }, - "settlementCurrency": "USD", - "paymentMethods": [ - { - "type": "blockchain", - "chain": "ALGO", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" - } - ], - "fees": [ - { - "type": "blockchainLeaseFee", - "amount": "3.14", - "currency": "USD" - } - ], - "paymentIds": [ - "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" - ], - "timeline": [ - { - "status": "created", - "context": "underpaid", - "time": "2020-04-10T02:13:30.000Z" - } - ], - "expiresOn": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z", - "createDate": "2020-04-10T02:13:30.000Z" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - } - } - } - }, - "/v1/paymentIntents/{id}": { - "get": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Get a payment intent", - "operationId": "getPaymentIntent", - "tags": [ - "Payment Intents" - ], - "parameters": [ - { - "$ref": "#/components/parameters/IdPath" - } - ], - "responses": { - "200": { - "description": "Successfully retrieved a payment intent.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "GetPaymentIntentResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/PaymentIntent" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "8755d0ea-14f9-4259-b092-de23c14b6568", - "amount": { - "amount": "3.14", - "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" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - } - } - } - }, - "/v1/paymentIntents/{id}/expire": { - "post": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Expire a payment intent", - "operationId": "expirePaymentIntent", - "tags": [ - "Payment Intents" - ], - "parameters": [ - { - "$ref": "#/components/parameters/IdPath" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "responses": { - "201": { - "description": "Successfully expired a payment intent.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "ExpirePaymentIntentResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/PaymentIntent" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "8755d0ea-14f9-4259-b092-de23c14b6568", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "amountPaid": { - "amount": "3.14", - "currency": "USD" - }, - "settlementCurrency": "USD", - "paymentMethods": [ - { - "type": "blockchain", - "chain": "ETH" - } - ], - "paymentIds": [], - "timeline": [ - { - "status": "expired", - "context": "underpaid", - "reason": "requested_by_merchant", - "time": "2022-07-21T21:45:54.569Z" - }, - { - "status": "created", - "time": "2022-07-21T20:13:35.579331Z" - } - ], - "createDate": "2022-07-21T20:13:35.578678Z", - "updateDate": "2022-07-21T20:19:24.859052Z" - } - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - } - } - } - }, - "/v1/payments": { - "get": { - "security": [ - { - "bearerAuth": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/Source" - }, - { - "$ref": "#/components/parameters/SettlementId" - }, - { - "$ref": "#/components/parameters/PaymentIntentId" - }, - { - "$ref": "#/components/parameters/PaymentSourceType" - }, - { - "$ref": "#/components/parameters/PaymentStatus" - }, - { - "$ref": "#/components/parameters/From" - }, - { - "$ref": "#/components/parameters/To" - }, - { - "$ref": "#/components/parameters/PageBefore" - }, - { - "$ref": "#/components/parameters/PageAfter" - }, - { - "$ref": "#/components/parameters/PageSize" - } - ], - "summary": "List all payments", - "operationId": "listPayments", - "tags": [ - "Payments" - ], - "responses": { - "200": { - "description": "Successfully retrieved a list of payments.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "ListPaymentsResponse", - "properties": { - "data": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/FiatPayment" - }, - { - "$ref": "#/components/schemas/CryptoPayment" - }, - { - "$ref": "#/components/schemas/FiatCancel" - }, - { - "$ref": "#/components/schemas/FiatRefund" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "Fiat Payment": "#/components/schemas/FiatPayment", - "Crypto Payment": "#/components/schemas/CryptoPayment", - "Fiat Cancel": "#/components/schemas/FiatCancel", - "Fiat Refund": "#/components/schemas/FiatRefund" - } - } - } - } - } - }, - "examples": { - "Fiat Payment": { - "value": { - "data": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "captured": false, - "captureAmount": { - "amount": "3.14", - "currency": "USD" - }, - "captureDate": "2020-04-10T02:13:30.000Z", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "description": "Payment", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - }, - "refunds": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - } - ], - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - ] - } - }, - "Crypto Payment": { - "value": { - "data": [ - { - "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de", - "type": "payment", - "status": "paid", - "amount": { - "amount": "1.00", - "currency": "USD" - }, - "fees": { - "amount": "0.01", - "currency": "USD" - }, - "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", - "createDate": "2022-07-21T20:16:35.092852Z", - "updateDate": "2022-07-21T20:19:24.719313Z" - } - ] - } - }, - "Fiat Cancel": { - "value": { - "data": [ - { - "id": "2dc266f5-0658-48ec-a81f-9c768279564d", - "type": "cancel", - "status": "confirmed", - "description": "Cancel Payment", - "amount": { - "amount": "10.00", - "currency": "USD" - }, - "createDate": "2022-04-21T21:50:34.274Z", - "updateDate": "2022-04-21T21:50:34.647839Z", - "merchantId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b", - "merchantWalletId": "1000174786", - "source": { - "id": "bc9157fe-5d73-48fe-9e77-9f6723bdcfeb", - "type": "card" - }, - "originalPayment": { - "id": "2812f549-062a-4bdd-8ee5-b521aa48a84d", - "type": "payment", - "status": "failed", - "createDate": "2022-04-21T21:47:41.501Z", - "updateDate": "2022-04-21T21:50:34.669012Z" - }, - "reason": "requested_by_customer" - } - ] - } - }, - "Fiat Refund": { - "value": { - "data": [ - { - "id": "03fbe7da-096a-4763-af77-e43006cd83be", - "type": "refund", - "status": "paid", - "description": "Refund Payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "fees": { - "amount": "0.00", - "currency": "USD" - }, - "createDate": "2022-04-21T12:49:21.146Z", - "updateDate": "2022-04-21T12:54:10.596976Z", - "merchantId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b", - "merchantWalletId": "1000174786", - "source": { - "id": "45fa5524-41b9-48ca-94cd-f45cb36cce4d", - "type": "card" - }, - "originalPayment": { - "id": "895f8db5-1d8c-407d-9533-b5ca3fbcc74e", - "type": "payment", - "status": "paid", - "createDate": "2022-04-06T19:33:29.690Z", - "updateDate": "2022-04-06T19:47:23.681180Z" - }, - "reason": "requested_by_customer" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - } - } - } - }, - "/v1/payments/{id}": { - "get": { - "parameters": [ - { - "$ref": "#/components/parameters/IdPath" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Get a payment", - "operationId": "getPayment", - "tags": [ - "Payments" - ], - "responses": { - "200": { - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "description": "Successfully retrieved a payment.", - "content": { - "application/json": { - "schema": { - "title": "GetPaymentResponse", - "properties": { - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/FiatPaymentPolymorphic" - }, - { - "$ref": "#/components/schemas/CryptoPayment" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "Fiat Payment": "#/components/schemas/FiatPayment", - "Crypto Payment": "#/components/schemas/CryptoPayment" - } - } - } - } - }, - "examples": { - "Fiat Payment": { - "value": { - "data": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "verification": { - "avs": "D", - "cvv": "not_requested", - "threeDSecure": "pass", - "eci": "00" - }, - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "captured": false, - "captureAmount": { - "amount": "3.14", - "currency": "USD" - }, - "captureDate": "2020-04-10T02:13:30.000Z", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "description": "Payment", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - }, - "refunds": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - } - ], - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - }, - "refunds": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "refund", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "description": "Payment", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - ], - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "trackingRef": "24910599141085313498894", - "externalRef": "YYYYMMDDXXXXXXXX012345", - "errorCode": "payment_failed", - "metadata": { - "email": "satoshi@circle.com", - "phoneNumber": "+14155555555" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "riskEvaluation": { - "decision": "approved", - "reason": "3000" - }, - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - } - } - }, - "Crypto Payment": { - "value": { - "data": { - "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de", - "type": "payment", - "status": "paid", - "amount": { - "amount": "1.00", - "currency": "USD" - }, - "fees": { - "amount": "0.01", - "currency": "USD" - }, - "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", - "createDate": "2022-07-21T20:16:35.092852Z", - "updateDate": "2022-07-21T20:19:24.719313Z" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - } - } - } - } - }, - "components": { - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } - }, - "parameters": { - "From": { - "name": "from", - "description": "Queries items created since the specified date-time (inclusive).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time", - "example": "2020-04-10T02:13:30.000Z" - } - }, - "To": { - "name": "to", - "description": "Queries items created before the specified date-time (inclusive).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "date-time", - "example": "2020-04-10T02:13:30.000Z" - } - }, - "PageBefore": { - "name": "pageBefore", - "description": "A collection ID value used for pagination.\n\nIt marks the exclusive end of a page. When provided, the collection resource will return the next `n` items before\nthe id, with `n` being specified by `pageSize`.\n\nThe items will be returned in the natural order of the collection.\n\nThe resource will return the first page if neither `pageAfter` nor `pageBefore` are specified.\n\nSHOULD NOT be used in conjuction with pageAfter.\n", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, - "PageAfter": { - "name": "pageAfter", - "description": "A collection ID value used for pagination.\n\nIt marks the exclusive begin of a page. When provided, the collection resource will return the next `n` items after\nthe id, with `n` being specified by `pageSize`.\n\nThe items will be returned in the natural order of the collection.\n\nThe resource will return the first page if neither `pageAfter` nor `pageBefore` are specified.\n\nSHOULD NOT be used in conjuction with pageBefore.\n", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, - "PageSize": { - "name": "pageSize", - "description": "Limits the number of items to be returned.\n\nSome collections have a strict upper bound that will disregard this value. In case the specified value is higher\nthan the allowed limit, the collection limit will be used.\n\nIf avoided, the collection will determine the page size itself.\n", - "in": "query", - "required": false, - "schema": { - "type": "integer", - "minimum": 1, - "example": 5 - } - }, - "IdPath": { - "name": "id", - "description": "Universally unique identifier (UUID v4) of a resource.", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid", - "example": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0" - } - }, - "Source": { - "name": "source", - "description": "Universally unique identifier (UUID v4) for the source. Filters results to fetch only payments made from the provdided source.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "uuid", - "example": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0" - } - }, - "SettlementId": { - "name": "settlementId", - "description": "Queries items with the specified settlement id. Matches any settlement id if unspecified.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "uuid", - "example": "b48c8962-8e9f-40c3-9f1d-d9adde2ffe61" - } - }, - "PaymentIntentId": { - "name": "paymentIntentId", - "description": "Queries items with the specified payment intent id.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "uuid", - "example": "b48c8962-8e9f-40c3-9f1d-d9adde2ffe61" - } - }, - "PaymentSourceType": { - "name": "type", - "description": "Source account type. Filters the results to fetch all payments made from a specified account type. Matches any source type if unspecified.", - "in": "query", - "required": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "card", - "wire", - "ach", - "sepa" - ] - } - } - }, - "PaymentStatus": { - "name": "status", - "description": "Queries items with the specified status. Matches any status if unspecified.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "pending", - "confirmed", - "paid", - "failed", - "action_required" - ] - } - } - }, - "headers": { - "XRequestId": { - "description": "Universally unique identifier (UUID v4) for the request. Helpful for identifying a request when communicating with Circle support.", - "schema": { - "type": "string", - "format": "uuid", - "example": "2adba88e-9d63-44bc-b975-9b6ae3440dde" - } - } - }, - "schemas": { - "IdempotencyKey": { - "type": "string", - "description": "Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.", - "format": "uuid", - "example": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7" - }, - "CryptoPaymentsMoney": { - "type": "object", - "required": [ - "amount", - "currency" - ], - "properties": { - "amount": { - "description": "Magnitude of the amount, in units of the currency, with a `.`.", - "type": "string", - "example": "3.14" - }, - "currency": { - "description": "Currency code.", - "type": "string", - "enum": [ - "USD", - "ETH", - "BTC" - ] - } - } - }, - "Chain": { - "type": "string", - "description": "A blockchain that a given currency is available on.", - "enum": [ - "ALGO", - "AVAX", - "BTC", - "ETH", - "FLOW", - "HBAR", - "MATIC", - "SOL", - "TRX", - "XLM" - ] - }, - "PaymentMethodBlockchain": { - "type": "object", - "required": [ - "type", - "chain" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "blockchain" - ] - }, - "chain": { - "$ref": "#/components/schemas/Chain" - }, - "address": { - "type": "string", - "readOnly": true, - "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" - } - } - }, - "PaymentIntentFees": { - "type": "object", - "readOnly": true, - "required": [ - "type", - "amount", - "currency" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "blockchainLeaseFee", - "totalPaymentFees" - ] - }, - "amount": { - "description": "Magnitude of the amount, in units of the currency, with a `.`.", - "type": "string", - "example": "3.14" - }, - "currency": { - "description": "Currency code.", - "type": "string", - "enum": [ - "USD" - ] - } - } - }, - "Timeline": { - "type": "object", - "readOnly": true, - "required": [ - "status", - "time" - ], - "properties": { - "status": { - "type": "string", - "enum": [ - "created", - "pending", - "complete", - "expired", - "failed" - ] - }, - "context": { - "type": "string", - "enum": [ - "underpaid", - "paid", - "overpaid" - ] - }, - "time": { - "description": "ISO-8601 UTC date/time format.", - "type": "string", - "format": "date-time" - } - } - }, - "UtcTimestampReadOnly": { - "type": "string", - "readOnly": true, - "description": "ISO-8601 UTC date/time format.", - "example": "2020-04-10T02:13:30.000Z" - }, - "PaymentIntent": { - "type": "object", - "required": [ - "idempotencyKey", - "amount", - "settlementCurrency", - "paymentMethods" - ], - "properties": { - "idempotencyKey": { - "$ref": "#/components/schemas/IdempotencyKey" - }, - "id": { - "type": "string", - "readOnly": true, - "description": "Unique system generated identifier for the entity.", - "format": "uuid", - "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" - }, - "amount": { - "$ref": "#/components/schemas/CryptoPaymentsMoney" - }, - "amountPaid": { - "description": "Sum of the the amount paid.", - "type": "object", - "readOnly": true, - "required": [ - "amount", - "currency" - ], - "properties": { - "amount": { - "description": "Magnitude of the amount, in units of the currency, with a `.`.", - "type": "string", - "example": "3.14" - }, - "currency": { - "description": "Currency code.", - "type": "string", - "enum": [ - "USD" - ] - } - } - }, - "settlementCurrency": { - "description": "Desired currency for the payments to settle in.", - "type": "string", - "enum": [ - "USD", - "BTC", - "ETH" - ] - }, - "paymentMethods": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentMethodBlockchain" - } - }, - "fees": { - "type": "array", - "readOnly": true, - "items": { - "$ref": "#/components/schemas/PaymentIntentFees" - } - }, - "paymentIds": { - "description": "List of associated payments.", - "type": "array", - "readOnly": true, - "items": { - "type": "string", - "format": "uuid", - "example": "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" - } - }, - "timeline": { - "description": "State management timeline.", - "type": "array", - "readOnly": true, - "items": { - "$ref": "#/components/schemas/Timeline" - } - }, - "expiresOn": { - "$ref": "#/components/schemas/UtcTimestampReadOnly" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestampReadOnly" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestampReadOnly" - } - } - }, - "Id": { - "type": "string", - "description": "Unique system generated identifier for the entity.", - "format": "uuid", - "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" - }, - "IdMerchant": { - "type": "string", - "description": "Unique system generated identifier for the merchant.", - "format": "uuid", - "example": "fc988ed5-c129-4f70-a064-e5beb7eb8e32" - }, - "MerchantWalletId": { - "type": "string", - "description": "Unique system generated identifier for the wallet of the merchant.", - "maxLength": 36, - "example": "212000" - }, - "FiatMoneyUsd": { - "type": "object", - "required": [ - "amount", - "currency" - ], - "properties": { - "amount": { - "description": "Magnitude of the amount, in units of the currency, with a `.`.", - "type": "string", - "example": "3.14" - }, - "currency": { - "description": "Currency code.", - "type": "string", - "enum": [ - "USD" - ] - } - } - }, - "SourceResponse": { - "type": "object", - "description": "The payment source.", - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "type": "string", - "description": "Type of the source.", - "enum": [ - "card", - "ach", - "wire", - "sepa" - ] - } - } - }, - "PaymentStatus": { - "type": "string", - "description": "Enumerated status of the payment. `pending` means the payment is waiting to be processed. `confirmed` means the payment has been approved by the bank and the merchant can treat it as successful, but settlement funds are not yet available to the merchant. `paid` means settlement funds have been received and are available to the merchant. `failed` means something went wrong (most commonly that the payment was denied). `action_required` means that additional steps are required to process this payment; refer to `requiredAction` for more details. Terminal states are `paid` and `failed`.", - "enum": [ - "pending", - "confirmed", - "paid", - "failed", - "action_required" - ] - }, - "UtcTimestamp": { - "type": "string", - "description": "ISO-8601 UTC date/time format.", - "example": "2020-04-10T02:13:30.000Z" - }, - "RequiredAction": { - "type": "object", - "description": "When the payment status is `action_required`, this object summarizes the required additional steps.", - "required": [ - "type", - "redirectUrl" - ], - "properties": { - "type": { - "type": "string", - "description": "The type of action that is required to proceed with the payment. Currently only one type is supported.", - "enum": [ - "three_d_secure_required" - ] - }, - "redirectUrl": { - "type": "string", - "description": "The URL to bring the user to in order to complete the payment.", - "example": "https://example.org" - } - } - }, - "CancelRefundReversalStatus": { - "type": "string", - "enum": [ - "pending", - "confirmed", - "paid", - "failed" - ], - "description": "Enumerated status of the payment. `pending` means the payment is waiting to be processed. `confirmed` means the payment has been approved by the bank and the merchant can treat it as successful, but settlement funds are not yet available to the merchant. `paid` means settlement funds have been received and are available to the merchant. `failed` means something went wrong (most commonly that the payment was denied). Terminal states are `paid` and `failed`." - }, - "PaymentInfoCancel": { - "type": "object", - "description": "Status information of the related cancel. This property is only present on canceled payment or refund items.", - "nullable": true, - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "type": "string", - "description": "Type of the payment object.", - "enum": [ - "cancel" - ] - }, - "description": { - "description": "Enumerated description of the payment item.", - "type": "string", - "nullable": true, - "enum": [ - "Payment" - ] - }, - "status": { - "$ref": "#/components/schemas/CancelRefundReversalStatus" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, - "PaymentInfoPaymentAndRefund": { - "type": "object", - "description": "Status information of the related payment. This property is only present on refund or cancel items.", - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "type": "string", - "description": "Type of the payment object.", - "enum": [ - "payment", - "refund" - ] - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "description": { - "type": "string", - "description": "Enumerated description of the payment item.", - "nullable": true, - "enum": [ - "Payment" - ] - }, - "status": { - "$ref": "#/components/schemas/PaymentStatus" - }, - "requiredAction": { - "$ref": "#/components/schemas/RequiredAction" - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, - "Channel": { - "type": "string", - "format": "uuid", - "description": "The channel identifier that can be set for the payment. When not provided, the default channel is used.", - "example": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7" - }, - "FiatPayment": { - "type": "object", - "description": "Status information of the related payment. This property is only present on refund or cancel items.", - "required": [ - "id", - "type", - "merchantId", - "amount", - "source", - "status" - ], - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "description": "Type of the payment object.", - "type": "string", - "enum": [ - "payment" - ] - }, - "merchantId": { - "$ref": "#/components/schemas/IdMerchant" - }, - "merchantWalletId": { - "$ref": "#/components/schemas/MerchantWalletId" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "source": { - "$ref": "#/components/schemas/SourceResponse" - }, - "description": { - "description": "Enumerated description of the payment.", - "type": "string", - "enum": [ - "Payment" - ] - }, - "status": { - "$ref": "#/components/schemas/PaymentStatus" - }, - "captured": { - "description": "Determines if a payment has successfully been captured. This property is only present for payments that did not use auto capture.", - "type": "boolean" - }, - "captureAmount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "captureDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "requiredAction": { - "$ref": "#/components/schemas/RequiredAction" - }, - "cancel": { - "$ref": "#/components/schemas/PaymentInfoCancel" - }, - "refunds": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentInfoPaymentAndRefund" - } - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "channel": { - "$ref": "#/components/schemas/Channel" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, - "CryptoPayment": { - "type": "object", - "description": "Status information of the related payment. This property is only present on refund or cancel items.", - "required": [ - "id", - "type", - "merchantId", - "amount", - "source", - "status" - ], - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "description": "Type of the payment object.", - "type": "string", - "enum": [ - "payment" - ] - }, - "merchantId": { - "$ref": "#/components/schemas/IdMerchant" - }, - "merchantWalletId": { - "$ref": "#/components/schemas/MerchantWalletId" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "status": { - "$ref": "#/components/schemas/PaymentStatus" - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "paymentIntentId": { - "type": "string", - "format": "uuid", - "example": "6e4d4047-db14-4c09-b238-1215aee50d03" - }, - "settlementAmount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "depositAddress": { - "type": "object", - "properties": { - "chain": { - "$ref": "#/components/schemas/Chain" - }, - "address": { - "type": "string", - "example": "0x97de855690955e0da79ce5c1b6804847e7070c7f" - } - } - }, - "transactionHash": { - "type": "string", - "example": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, - "FiatCancel": { - "type": "object", - "description": "Status information of the related cancel. This property is only present on canceled payment or refund items.", - "nullable": true, - "required": [ - "id", - "type", - "merchantId", - "amount", - "source", - "status" - ], - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "type": "string", - "description": "Type of the payment object.", - "enum": [ - "cancel" - ] - }, - "merchantId": { - "$ref": "#/components/schemas/IdMerchant" - }, - "merchantWalletId": { - "$ref": "#/components/schemas/MerchantWalletId" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "source": { - "$ref": "#/components/schemas/SourceResponse" - }, - "description": { - "description": "Enumerated description of the payment.", - "type": "string", - "enum": [ - "Payment" - ] - }, - "status": { - "$ref": "#/components/schemas/CancelRefundReversalStatus" - }, - "originalPayment": { - "$ref": "#/components/schemas/PaymentInfoPaymentAndRefund" - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "channel": { - "$ref": "#/components/schemas/Channel" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, - "FiatRefund": { - "type": "object", - "required": [ - "id", - "type", - "merchantId", - "amount", - "source", - "status" - ], - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "description": "Type of the payment object.", - "type": "string", - "enum": [ - "refund" - ] - }, - "merchantId": { - "$ref": "#/components/schemas/IdMerchant" - }, - "merchantWalletId": { - "$ref": "#/components/schemas/MerchantWalletId" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "source": { - "$ref": "#/components/schemas/SourceResponse" - }, - "description": { - "description": "Enumerated description of the payment.", - "type": "string", - "enum": [ - "Payment" - ] - }, - "status": { - "$ref": "#/components/schemas/CancelRefundReversalStatus" - }, - "originalPayment": { - "$ref": "#/components/schemas/PaymentInfoPaymentAndRefund" - }, - "cancel": { - "$ref": "#/components/schemas/PaymentInfoCancel" - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "channel": { - "$ref": "#/components/schemas/Channel" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, - "AvsResults": { - "type": "string", - "description": "Status of the AVS check. Raw AVS response, expressed as an upper-case letter. `not_requested` indicates check was not made. `pending` is pending/processing.", - "example": "D" - }, - "CvvResults": { - "description": "Enumerated status of the check. `not_requested` indicates check was not made. `pass` indicates value is correct. `fail` indicates value is incorrect. `unavailable` indicates card issuer did not do the provided check. `pending` indicates check is pending/processing.", - "type": "string", - "enum": [ - "not_requested", - "pass", - "fail", - "unavailable", - "pending" - ] - }, - "ThreeDsResult": { - "type": "string", - "description": "Enumerated status of the check. `pass` indicates successful 3DS authentication. `fail` indicates failed 3DS authentication.", - "enum": [ - "pass", - "fail" - ] - }, - "Eci": { - "type": "string", - "description": "ECI (electronic commerce indicator) value returned by Directory Servers (namely Visa, MasterCard, JCB, and American Express) indicating the outcome of authentication attempted on transactions enforced by 3DS.", - "enum": [ - "00", - "01", - "02", - "05", - "06", - "07" - ] - }, - "PaymentVerificationResponse": { - "type": "object", - "description": "Indicates the status of the payment verification. This property will be present once the payment is confirmed.", - "required": [ - "avs", - "cvv" - ], - "properties": { - "avs": { - "$ref": "#/components/schemas/AvsResults" - }, - "cvv": { - "$ref": "#/components/schemas/CvvResults" - }, - "threeDSecure": { - "$ref": "#/components/schemas/ThreeDsResult" - }, - "eci": { - "$ref": "#/components/schemas/Eci" - } - } - }, - "ExternalRef": { - "type": "string", - "description": "External network identifier which will be present once provided from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability Data (IMAD/OMAD)**: unique number given to each FedWire payment when using the Federal Reserve Bank Service which can be used to investigate and track wire transfers.\n", - "example": "YYYYMMDDXXXXXXXX012345" - }, - "PaymentErrorCode": { - "type": "string", - "description": "Indicates the failure reason of a payment. Only present for payments in failed state. Possible values are [`payment_failed`, `payment_fraud_detected`, `payment_denied`, `payment_not_supported_by_issuer`, `payment_not_funded`, `payment_unprocessable`, `payment_stopped_by_issuer`, `payment_canceled`, `payment_returned`, `payment_failed_balance_check`, `card_failed`, `card_invalid`, `card_address_mismatch`, `card_zip_mismatch`, `card_cvv_invalid`, `card_expired`, `card_limit_violated`, `card_not_honored`, `card_cvv_required`, `credit_card_not_allowed`, `card_account_ineligible`, `card_network_unsupported`, `channel_invalid`, `unauthorized_transaction`, `bank_account_ineligible`, `bank_transaction_error`, `invalid_account_number`, `invalid_wire_rtn`, `invalid_ach_rtn`, `vendor_inactive`]'", - "nullable": true, - "enum": [ - "payment_failed", - "payment_fraud_detected", - "payment_denied", - "payment_not_supported_by_issuer", - "payment_not_funded", - "payment_unprocessable", - "payment_stopped_by_issuer", - "payment_canceled", - "payment_returned", - "payment_failed_balance_check", - "card_failed", - "card_invalid", - "card_address_mismatch", - "card_zip_mismatch", - "card_cvv_invalid", - "card_expired", - "card_limit_violated", - "card_not_honored", - "card_cvv_required", - "card_restricted,", - "card_account_ineligible", - "card_network_unsupported", - "channel_invalid", - "unauthorized_transaction", - "bank_account_ineligible", - "bank_transaction_error", - "invalid_account_number", - "invalid_wire_rtn", - "invalid_ach_rtn", - "ref_id_invalid", - "account_name_mismatch", - "account_number_mismatch", - "account_ineligible", - "wallet_address_mismatch", - "customer_name_mismatch", - "institution_name_mismatch", - "vendor_inactive" - ] - }, - "Email": { - "type": "string", - "description": "Email of the user.", - "maxLength": 1024, - "example": "satoshi@circle.com" - }, - "PhoneNumber": { - "type": "string", - "description": "Phone number of the user in E.164 format. We recommend using a library such as [libphonenumber](https://github.com/google/libphonenumber) to parse and validate phone numbers.", - "maxLength": 16, - "pattern": "/\\+?[1-9]\\d{1,14}/", - "example": "+14155555555" - }, - "MetadataPhoneEmail": { - "type": "object", - "required": [ - "email" - ], - "properties": { - "email": { - "$ref": "#/components/schemas/Email" - }, - "phoneNumber": { - "$ref": "#/components/schemas/PhoneNumber" - } - } - }, - "RiskEvaluation": { - "type": "object", - "description": "Results of risk evaluation. Only present if the payment is denied by Circle's risk service.", - "nullable": true, - "properties": { - "decision": { - "description": "Enumerated decision of the account.", - "type": "string", - "enum": [ - "approved", - "denied", - "review" - ] - }, - "reason": { - "description": "Risk reason for the definitive decision outcome.", - "type": "string", - "nullable": true, - "example": "3000" - } - } - }, - "FiatPaymentPolymorphic": { - "type": "object", - "required": [ - "id", - "type", - "merchantId", - "amount", - "source", - "status" - ], - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "type": { - "description": "Type of the payment object.", - "type": "string", - "enum": [ - "payment", - "refund", - "cancel" - ] - }, - "merchantId": { - "$ref": "#/components/schemas/IdMerchant" - }, - "merchantWalletId": { - "$ref": "#/components/schemas/MerchantWalletId" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "source": { - "$ref": "#/components/schemas/SourceResponse" - }, - "description": { - "description": "Enumerated description of the payment.", - "type": "string", - "enum": [ - "Payment" - ] - }, - "status": { - "$ref": "#/components/schemas/PaymentStatus" - }, - "requiredAction": { - "$ref": "#/components/schemas/RequiredAction" - }, - "verification": { - "$ref": "#/components/schemas/PaymentVerificationResponse" - }, - "originalPayment": { - "$ref": "#/components/schemas/FiatPayment" - }, - "cancel": { - "$ref": "#/components/schemas/FiatCancel" - }, - "refunds": { - "type": "array", - "nullable": true, - "items": { - "$ref": "#/components/schemas/FiatRefund" - } - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "trackingRef": { - "description": "Payment tracking reference. Will be present once known.", - "type": "string", - "nullable": true, - "example": "24910599141085313498894" - }, - "externalRef": { - "$ref": "#/components/schemas/ExternalRef" - }, - "errorCode": { - "$ref": "#/components/schemas/PaymentErrorCode" - }, - "metadata": { - "$ref": "#/components/schemas/MetadataPhoneEmail" - }, - "channel": { - "$ref": "#/components/schemas/Channel" - }, - "riskEvaluation": { - "$ref": "#/components/schemas/RiskEvaluation" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - } - }, - "responses": { - "NotAuthorized": { - "description": "The request has not been applied because it lacks valid authentication credentials.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "title": "NotAuthorized", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "example": 400 - }, - "message": { - "type": "string", - "example": "Something went wrong." - } - }, - "example": { - "code": 401, - "message": "Malformed authorization." - } - }, - "examples": { - "response": { - "value": { - "code": 401, - "message": "Malformed authorization." - } - } - } - } - } - }, - "BadRequest": { - "description": "The request cannot be processed due to a client error.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "title": "BadRequest", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "example": 400 - }, - "message": { - "type": "string", - "example": "Something went wrong." - } - }, - "example": { - "code": 400, - "message": "Bad request." - } - }, - "examples": { - "response": { - "value": { - "code": 400, - "message": "Bad request." - } - } - } - } - } - }, - "NotFound": { - "description": "The specified resource was not found.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "title": "NotFound", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "example": 400 - }, - "message": { - "type": "string", - "example": "Something went wrong." - } - }, - "example": { - "code": 404, - "message": "Not found." - } - }, - "examples": { - "response": { - "value": { - "code": 404, - "message": "Not found." - } - } - } - } - } - } - } - } -} \ No newline at end of file diff --git a/openapi/json/general.json b/openapi/json/general.json index 1dc8a53..88af55e 100644 --- a/openapi/json/general.json +++ b/openapi/json/general.json @@ -2,11 +2,11 @@ "openapi": "3.0.2", "servers": [ { - "url": "api-sandbox.circle.com" + "url": "https://api-sandbox.circle.com" } ], "info": { - "version": "1.0.3", + "version": "1.1.0", "title": "API Overview", "description": "Common endpoints shared across all Circle APIs." }, @@ -162,122 +162,122 @@ } }, "/v1/notifications/subscriptions": { - "get": { + "post": { "security": [ { "bearerAuth": [] } ], - "summary": "List all notification subscriptions", - "description": "Retrieve a list of existing notification subscriptions with details.", - "parameters": [], - "operationId": "listSubscriptions", + "summary": "Create a notification subscription", + "description": "Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error.\n", + "operationId": "createSubscription", "tags": [ "Subscriptions" ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubscriptionRequest" + } + } + } + }, "responses": { "200": { - "description": "Successfully retrieved a list of notification subscriptions.", + "description": "Successfully created a notification subscription.", "content": { "application/json": { "schema": { - "title": "ListSubscriptionsResponse", + "title": "CreateSubscriptionResponse", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SubscriptionResponse" - } + "$ref": "#/components/schemas/SubscriptionResponse" } } }, "examples": { "response": { "value": { - "data": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "endpoint": "https://example.org/handler/for/notifications", - "subscriptionDetails": [ - { - "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", - "status": "confirmed" - } - ] - } - ] + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "endpoint": "https://example.org/handler/for/notifications", + "subscriptionDetails": [ + { + "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", + "status": "confirmed" + } + ] + } } } } } } }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, "401": { "$ref": "#/components/responses/NotAuthorized" + }, + "429": { + "$ref": "#/components/responses/LimitExceeded" } } }, - "post": { + "get": { "security": [ { "bearerAuth": [] } ], - "summary": "Create a notification subscription", - "description": "Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error.\n", - "operationId": "createSubscribtion", + "summary": "List all notification subscriptions", + "description": "Retrieve a list of existing notification subscriptions with details.", + "parameters": [], + "operationId": "listSubscriptions", "tags": [ "Subscriptions" ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SubscriptionRequest" - } - } - } - }, "responses": { "200": { - "description": "Successfully created a notification subscription.", + "description": "Successfully retrieved a list of notification subscriptions.", "content": { "application/json": { "schema": { - "title": "CreateSubscribtionResponse", + "title": "ListSubscriptionsResponse", "properties": { "data": { - "$ref": "#/components/schemas/SubscriptionResponse" + "type": "array", + "items": { + "$ref": "#/components/schemas/SubscriptionResponse" + } } } }, "examples": { "response": { "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "endpoint": "https://example.org/handler/for/notifications", - "subscriptionDetails": [ - { - "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", - "status": "confirmed" - } - ] - } + "data": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "endpoint": "https://example.org/handler/for/notifications", + "subscriptionDetails": [ + { + "url": "arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17", + "status": "confirmed" + } + ] + } + ] } } } } } }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, "401": { "$ref": "#/components/responses/NotAuthorized" - }, - "429": { - "$ref": "#/components/responses/LimitExceeded" } } } @@ -296,7 +296,7 @@ ], "summary": "Remove a notification subscription", "description": "To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed.", - "operationId": "deleteSubscribtion", + "operationId": "deleteSubscription", "tags": [ "Subscriptions" ], @@ -311,7 +311,7 @@ "content": { "application/json": { "schema": { - "title": "DeleteSubscribtionResponse", + "title": "DeleteSubscriptionResponse", "properties": { "data": { "$ref": "#/components/schemas/UnsubscribeResponse" diff --git a/openapi/json/payments.json b/openapi/json/payments.json index 9f41ea6..d4ac7f6 100644 --- a/openapi/json/payments.json +++ b/openapi/json/payments.json @@ -2,48 +2,262 @@ "openapi": "3.0.2", "servers": [ { - "url": "api-sandbox.circle.com" + "url": "https://api-sandbox.circle.com" } ], "info": { - "version": "1.0.3", + "version": "1.1.0", "title": "Payments API", - "description": "APIs for accepting payments." + "description": "The Circle Payments API allows you to take payments from your end users via traditional methods such as debit & credit cards, bank accounts (wires and ACH), etc., and receive settlement in USDC.\n\nThe Circle Payments API has been designed with any business or internet commerce in mind, not just crypto applications, and it's based on Circle's extensive experience processing millions of card payments since 2014.\n" }, "tags": [ { - "name": "Payments" + "name": "Payments", + "description": "Create, cancel, refund, and get updates on card and ACH payments." }, { - "name": "On-chain payments" + "name": "Crypto Payment Intents", + "description": "Create and track intent for end user to pay via crypto." }, { - "name": "Cards" + "name": "Cards", + "description": "Link, update, and get information on debit/credit cards." }, { - "name": "Wires" + "name": "Payment Tokens", + "description": "Create Apple Pay and Google Pay payment tokens." }, { - "name": "ACH" + "name": "Wires", + "description": "Create, get instructions, and get information on bank accounts for wire transfers." }, { - "name": "SEPA" + "name": "ACH", + "description": "Link and get information on bank account for ACH payments." }, { - "name": "Settlements" + "name": "SEPA", + "description": "Create and get information on SEPA accounts." }, { - "name": "Chargebacks" + "name": "Settlements", + "description": "Get information on settlement batches." }, { - "name": "Reversals" + "name": "Chargebacks", + "description": "Get information on card chargebacks." }, { - "name": "Balances" + "name": "Reversals", + "description": "Get information on ACH reversals." + }, + { + "name": "Balances", + "description": "Get information on settled and unsettled balances." } ], "paths": { "/v1/payments": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a payment", + "operationId": "createPayment", + "tags": [ + "Payments" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentCreationRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully created a payment.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreatePaymentResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/DetailedPayment" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "captured": false, + "captureAmount": { + "amount": "3.14", + "currency": "USD" + }, + "captureDate": "2020-04-10T02:13:30.000Z", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "verification": { + "avs": "D", + "cvv": "not_requested", + "threeDSecure": "pass", + "eci": "00" + }, + "cancel": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "cancel", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "originalPayment": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "description": "Payment", + "status": "pending", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "createDate": "2020-04-10T02:13:30.000Z" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + }, + "refunds": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "refund", + "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", + "merchantWalletId": "212000", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "source": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "card" + }, + "description": "Payment", + "status": "pending", + "originalPayment": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "payment", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "description": "Payment", + "status": "pending", + "requiredAction": { + "type": "three_d_secure_required", + "redirectUrl": "https://example.org" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "createDate": "2020-04-10T02:13:30.000Z" + }, + "cancel": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "type": "cancel", + "description": "Payment", + "status": "pending", + "createDate": "2020-04-10T02:13:30.000Z" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + ], + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "trackingRef": "24910599141085313498894", + "errorCode": "payment_failed", + "metadata": { + "email": "satoshi@circle.com", + "phoneNumber": "+14155555555" + }, + "riskEvaluation": { + "decision": "approved", + "reason": "3000" + }, + "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + }, "get": { "security": [ { @@ -307,206 +521,6 @@ "$ref": "#/components/responses/NotAuthorized" } } - }, - "post": { - "security": [ - { - "bearerAuth": [] - } - ], - "summary": "Create a payment", - "operationId": "createPayment", - "tags": [ - "Payments" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PaymentCreationRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Successfully created a payment.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "CreatePaymentResponse", - "properties": { - "data": { - "$ref": "#/components/schemas/DetailedPayment" - } - } - }, - "examples": { - "response": { - "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "captured": false, - "captureAmount": { - "amount": "3.14", - "currency": "USD" - }, - "captureDate": "2020-04-10T02:13:30.000Z", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "verification": { - "avs": "D", - "cvv": "not_requested", - "threeDSecure": "pass", - "eci": "00" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - }, - "refunds": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "refund", - "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", - "merchantWalletId": "212000", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "source": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "card" - }, - "description": "Payment", - "status": "pending", - "originalPayment": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "payment", - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "description": "Payment", - "status": "pending", - "requiredAction": { - "type": "three_d_secure_required", - "redirectUrl": "https://example.org" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "createDate": "2020-04-10T02:13:30.000Z" - }, - "cancel": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "type": "cancel", - "description": "Payment", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - }, - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - ], - "fees": { - "amount": "3.14", - "currency": "USD" - }, - "trackingRef": "24910599141085313498894", - "errorCode": "payment_failed", - "metadata": { - "email": "satoshi@circle.com", - "phoneNumber": "+14155555555" - }, - "riskEvaluation": { - "decision": "approved", - "reason": "3000" - }, - "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "createDate": "2020-04-10T02:13:30.000Z", - "updateDate": "2020-04-10T02:13:30.000Z" - } - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/NotAuthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - } - } } }, "/v1/payments/{id}": { @@ -551,7 +565,7 @@ "discriminator": { "propertyName": "type", "mapping": { - "Fiat Payment": "#/components/schemas/FiatPayment", + "Fiat Payment": "#/components/schemas/FiatPaymentPolymorphic", "Crypto Payment": "#/components/schemas/CryptoPayment" } } @@ -1217,9 +1231,78 @@ "bearerAuth": [] } ], - "summary": "Create a mock Wire payment", - "description": "In the sandbox environment, initiate a mock wire payment that mimics the behavior of funds sent through the bank (wire) account linked to master wallet.", - "operationId": "createMockWirePayment", + "summary": "Create a mock Wire payment", + "description": "In the sandbox environment, initiate a mock wire payment that mimics the behavior of funds sent through the bank (wire) account linked to master wallet.", + "operationId": "createMockWirePayment", + "tags": [ + "Payments" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MockWirePaymentRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully created a mock wire payment.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreateWirePaymentResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/MockWirePaymentResponse" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "trackingRef": "CIR13FB13A", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "beneficiaryBank": { + "accountNumber": "11111111" + }, + "status": "pending" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + } + }, + "/v1/mocks/payments/sepa": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a mock SEPA payment", + "description": "In the sandbox environment, initiate a mock SEPA payment that mimics the behavior of funds sent through the bank (SEPA) account linked to master wallet.", + "operationId": "createMockSepaPayment", "tags": [ "Payments" ], @@ -1227,14 +1310,21 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MockWirePaymentRequest" + "$ref": "#/components/schemas/MockSepaPaymentRequest" + }, + "example": { + "trackingRef": "CIR13FB13A", + "amount": { + "amount": 3.14, + "currency": "EUR" + } } } } }, "responses": { "201": { - "description": "Successfully created a mock wire payment.", + "description": "Successfully created a mock SEPA payment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -1243,10 +1333,10 @@ "content": { "application/json": { "schema": { - "title": "CreateWirePaymentResponse", + "title": "CreateSepaPaymentResponse", "properties": { "data": { - "$ref": "#/components/schemas/MockWirePaymentResponse" + "$ref": "#/components/schemas/MockSepaPaymentResponse" } } }, @@ -1259,9 +1349,6 @@ "amount": "3.14", "currency": "USD" }, - "beneficiaryBank": { - "accountNumber": "11111111" - }, "status": "pending" } } @@ -1279,38 +1366,30 @@ } } }, - "/v1/mocks/payments/sepa": { + "/v1/paymentIntents": { "post": { "security": [ { "bearerAuth": [] } ], - "summary": "Create a mock SEPA payment", - "description": "In the sandbox environment, initiate a mock SEPA payment that mimics the behavior of funds sent through the bank (SEPA) account linked to master wallet.", - "operationId": "createMockSepaPayment", + "summary": "Create a payment intent", + "operationId": "createPaymentIntent", "tags": [ - "Payments" + "Crypto Payment Intents" ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MockSepaPaymentRequest" - }, - "example": { - "trackingRef": "CIR13FB13A", - "amount": { - "amount": 3.14, - "currency": "EUR" - } + "$ref": "#/components/schemas/PaymentIntent" } } } }, "responses": { "201": { - "description": "Successfully created a mock SEPA payment.", + "description": "Successfully created a payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -1319,10 +1398,10 @@ "content": { "application/json": { "schema": { - "title": "CreateSepaPaymentResponse", + "title": "CreatePaymentIntentResponse", "properties": { "data": { - "$ref": "#/components/schemas/MockSepaPaymentResponse" + "$ref": "#/components/schemas/PaymentIntent" } } }, @@ -1330,12 +1409,31 @@ "response": { "value": { "data": { - "trackingRef": "CIR13FB13A", + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "amount": { "amount": "3.14", "currency": "USD" }, - "status": "pending" + "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" } } } @@ -1348,51 +1446,54 @@ }, "401": { "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" } } - } - }, - "/v1/transfers": { + }, "get": { "security": [ { "bearerAuth": [] } ], + "summary": "List all payment intents", + "operationId": "listPaymentIntents", + "tags": [ + "Crypto Payment Intents" + ], "parameters": [ { - "name": "walletId", - "description": "Unique identifier for the source or destination wallet of transfers, if any. May not be used in conjunction with destinationWalletId or sourceWalletId. Useful for fetching all transfers related to a wallet.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "example": "12345" - } - }, - { - "name": "sourceWalletId", - "description": "Unique identifier for the source wallet of transfers, if any.", + "name": "status", + "description": "Filters by the most recent `timeline.status` within the payment intent.", "in": "query", "required": false, "schema": { "type": "string", - "example": "12345" + "enum": [ + "created", + "pending", + "complete", + "expired", + "failed" + ] } }, { - "name": "destinationWalletId", - "description": "Unique identifier for the destination wallet of transfers, if any.", + "name": "context", + "description": "Filters by the most recent `timeline.context` within the payment intent.", "in": "query", "required": false, "schema": { "type": "string", - "example": "12345" + "enum": [ + "underpaid", + "paid", + "overpaid" + ] } }, - { - "$ref": "#/components/parameters/ReturnIdentities" - }, { "$ref": "#/components/parameters/From" }, @@ -1409,15 +1510,9 @@ "$ref": "#/components/parameters/PageSize" } ], - "summary": "List all transfers", - "description": "Searches for transfers involving the provided wallets. If no wallet ids are provided, searches all wallets associated with your Circle API account. If the date parameters are omitted, returns the most recent transfers. This endpoint returns up to 50 transfers in descending chronological order or pageSize, if provided.", - "operationId": "listTransfers", - "tags": [ - "On-chain payments" - ], "responses": { "200": { - "description": "Successfully retrieved a list of transfers.", + "description": "Successfully retrieved a list of payment intents.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -1426,12 +1521,12 @@ "content": { "application/json": { "schema": { - "title": "ListTransfersResponse", + "title": "ListPaymentIntentsResponse", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Transfer" + "$ref": "#/components/schemas/PaymentIntent" } } } @@ -1442,22 +1537,41 @@ "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "source": { - "type": "wallet", - "id": "12345" - }, - "destination": { - "type": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "addressTag": "123456789", - "chain": "ALGO" - }, "amount": { "amount": "3.14", "currency": "USD" }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", - "status": "pending", + "amountPaid": { + "amount": "3.14", + "currency": "USD" + }, + "settlementCurrency": "USD", + "paymentMethods": [ + { + "type": "blockchain", + "chain": "ALGO", + "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" + } + ], + "fees": [ + { + "type": "blockchainLeaseFee", + "amount": "3.14", + "currency": "USD" + } + ], + "paymentIds": [ + "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" + ], + "timeline": [ + { + "status": "created", + "context": "underpaid", + "time": "2020-04-10T02:13:30.000Z" + } + ], + "expiresOn": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z", "createDate": "2020-04-10T02:13:30.000Z" } ] @@ -1473,41 +1587,38 @@ } } }, - "/v1/transfers/{id}": { + "/v1/paymentIntents/{id}": { "get": { - "parameters": [ - { - "$ref": "#/components/parameters/IdPath" - }, - { - "$ref": "#/components/parameters/ReturnIdentities" - } - ], "security": [ { "bearerAuth": [] } ], - "summary": "Get a transfer", - "operationId": "getTransfer", + "summary": "Get a payment intent", + "operationId": "getPaymentIntent", "tags": [ - "On-chain payments" + "Crypto Payment Intents" + ], + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } ], "responses": { "200": { + "description": "Successfully retrieved a payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, - "description": "Successfully retrieved a transfer.", "content": { "application/json": { "schema": { - "title": "GetTransferResponse", + "title": "GetPaymentIntentResponse", "properties": { "data": { - "$ref": "#/components/schemas/TransferDetailedTransfer" + "$ref": "#/components/schemas/PaymentIntent" } } }, @@ -1515,63 +1626,76 @@ "response": { "value": { "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "source": { - "type": "wallet", - "id": "12345" - }, - "destination": { - "type": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", "amount": { "amount": "3.14", "currency": "USD" }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" + "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" } } } } } } + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" } } } }, - "/v1/wallets/{walletId}/addresses": { + "/v1/paymentIntents/{id}/expire": { "post": { - "parameters": [ - { - "$ref": "#/components/parameters/WalletId" - } - ], "security": [ { "bearerAuth": [] } ], - "summary": "Create a blockchain address", - "description": "Generates a new blockchain address for a wallet for a given currency/chain pair. Circle may reuse addresses on blockchains that support reuse. For example, if you're requesting two addresses for depositing USD and ETH, both on Ethereum, you may see the same Ethereum address returned. Depositing cryptocurrency to a generated address will credit the associated wallet with the value of the deposit.\n", - "operationId": "generateAddress", + "summary": "Expire a payment intent", + "operationId": "expirePaymentIntent", "tags": [ - "On-chain payments" + "Crypto Payment Intents" + ], + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GenerateAddressRequest" + "type": "object" } } } }, "responses": { "201": { - "description": "Successfully generated a new address.", + "description": "Successfully expired a payment intent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -1580,10 +1704,10 @@ "content": { "application/json": { "schema": { - "title": "GenerateAddressResponse", + "title": "ExpirePaymentIntentResponse", "properties": { "data": { - "$ref": "#/components/schemas/AddressObject" + "$ref": "#/components/schemas/PaymentIntent" } } }, @@ -1591,10 +1715,37 @@ "response": { "value": { "data": { - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "addressTag": "123456789", - "currency": "USD", - "chain": "ALGO" + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "amountPaid": { + "amount": "3.14", + "currency": "USD" + }, + "settlementCurrency": "USD", + "paymentMethods": [ + { + "type": "blockchain", + "chain": "ETH" + } + ], + "paymentIds": [], + "timeline": [ + { + "status": "expired", + "context": "underpaid", + "reason": "requested_by_merchant", + "time": "2022-07-21T21:45:54.569Z" + }, + { + "status": "created", + "time": "2022-07-21T20:13:35.579331Z" + } + ], + "createDate": "2022-07-21T20:13:35.578678Z", + "updateDate": "2022-07-21T20:19:24.859052Z" } } } @@ -1605,86 +1756,8 @@ "400": { "$ref": "#/components/responses/BadRequest" }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "409": { - "$ref": "#/components/responses/Conflict" - } - } - }, - "get": { - "security": [ - { - "bearerAuth": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/WalletId" - }, - { - "$ref": "#/components/parameters/From" - }, - { - "$ref": "#/components/parameters/To" - }, - { - "$ref": "#/components/parameters/PageBefore" - }, - { - "$ref": "#/components/parameters/PageAfter" - }, - { - "$ref": "#/components/parameters/PageSize" - } - ], - "summary": "List all addresses", - "description": "Retrieves a list of addresses associated with a wallet.", - "operationId": "listAddresses", - "tags": [ - "On-chain payments" - ], - "responses": { - "200": { - "description": "Successfully retrieved a list of addresses.", - "headers": { - "X-Request-Id": { - "$ref": "#/components/headers/XRequestId" - } - }, - "content": { - "application/json": { - "schema": { - "title": "ListAddressesResponse", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AddressObject" - } - } - } - }, - "examples": { - "response": { - "value": { - "data": [ - { - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "addressTag": "123456789", - "currency": "USD", - "chain": "ALGO" - } - ] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" + "401": { + "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" @@ -1843,6 +1916,7 @@ "network": "VISA", "bin": "401230", "issuerCountry": "US", + "fundingType": "credit", "fingerprint": "eb170539-9e1c-4e92-bf4f-1d09534fdca2", "verification": { "avs": "D", @@ -2047,6 +2121,80 @@ } } }, + "/v1/paymentTokens": { + "post": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Create a payment token", + "description": "Convert a digital wallet (Apple Pay, Google Pay) token to a single-use payment token.", + "operationId": "createPaymentToken", + "tags": [ + "Payment Tokens" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentTokenRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully converted a digital token to a Circle token account.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "CreatePaymentTokenResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/PaymentToken" + } + } + }, + "examples": { + "response": { + "value": { + "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" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + } + }, "/v1/banks/wires": { "post": { "security": [ @@ -2497,7 +2645,7 @@ "content": { "application/json": { "schema": { - "title": "CreateAchAccountResponse", + "title": "CreateMockAchAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/MockAchAccountResponse" @@ -2988,6 +3136,7 @@ "paymentId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "reasonCode": "10.4", + "status": "active", "category": "Canceled Recurring Payment", "history": [ { @@ -3065,6 +3214,7 @@ "paymentId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32", "reasonCode": "10.4", + "status": "active", "category": "Canceled Recurring Payment", "history": [ { @@ -3363,6 +3513,7 @@ "required": false, "schema": { "type": "array", + "uniqueItems": true, "items": { "type": "string", "enum": [ @@ -3452,27 +3603,6 @@ "example": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0" } }, - "ReturnIdentities": { - "name": "returnIdentities", - "description": "Specify if you would like to see identities in the response. Restricts maximum returned items to 5. By default returnIdentities is false, resulting in the response not returning `data.source.identities`.", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "example": "true", - "default": false - } - }, - "WalletId": { - "name": "walletId", - "description": "Identifier for the wallet.", - "in": "path", - "required": true, - "schema": { - "type": "string", - "example": "0123456789" - } - }, "PaymentId": { "name": "paymentId", "description": "The payment ID associated with the chargeback.", @@ -4762,114 +4892,30 @@ } } }, - "IdentityAddress": { - "type": "object", - "required": [ - "line1", - "city", - "district", - "postalCode", - "country" - ], - "properties": { - "line1": { - "type": "string", - "description": "Line one of the street address.", - "maxLength": 1024, - "example": "100 Money Street" - }, - "line2": { - "type": "string", - "description": "Line two of the street address.", - "maxLength": 1024, - "example": "Suite 1" - }, - "city": { - "type": "string", - "description": "City portion of the address.", - "maxLength": 1024, - "example": "Boston" - }, - "district": { - "description": "State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.", - "type": "string", - "maxLength": 16, - "example": "MA" - }, - "postalCode": { - "type": "string", - "description": "Postal / ZIP code of the address.", - "maxLength": 16, - "example": "01234" - }, - "country": { - "type": "string", - "description": "Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.", - "maxLength": 2, - "example": "US" - } - } - }, - "Identity": { + "CryptoPaymentsMoney": { "type": "object", - "description": "The identity of the originator. Identities are required when:\n * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n * `amount.amount` >= $3,000 in value\n", "required": [ - "type", - "name", - "addresses" + "amount", + "currency" ], "properties": { - "type": { - "type": "string", - "description": "The type of identity for the originator.\n* `individual` - A uniquely distinguishable individual.\n* `business` - Any entity other than a natural person that can establish a permanent customer relationship with an affected entity or otherwise own property. This can include companies, foundations, anstalt, partnerships, associations and other relevantly similar entities.\n", - "enum": [ - "individual", - "business" - ] - }, - "name": { + "amount": { + "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", - "description": "Full name of the identity.", - "example": "Satoshi Nakamoto", - "maxLength": 1024 + "example": "3.14" }, - "addresses": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentityAddress" - } - } - } - }, - "TransferSourceWalletLocation": { - "description": "A source wallet location.", - "type": "object", - "required": [ - "type", - "id" - ], - "properties": { - "type": { + "currency": { + "description": "Currency code.", "type": "string", "enum": [ - "wallet" + "USD", + "ETH", + "BTC" ] - }, - "id": { - "type": "string", - "description": "The id of the wallet.", - "example": "12345" - }, - "identities": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Identity" - } } } }, - "TransferSourceBlockchainLocation": { - "description": "A source blockchain address.", + "PaymentMethodBlockchain": { "type": "object", "required": [ "type", @@ -4885,330 +4931,161 @@ "chain": { "$ref": "#/components/schemas/Chain" }, - "identities": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Identity" - } - } - } - }, - "TransferSourceLocation": { - "description": "A source of funds.", - "oneOf": [ - { - "$ref": "#/components/schemas/TransferSourceWalletLocation" - }, - { - "$ref": "#/components/schemas/TransferSourceBlockchainLocation" - } - ], - "discriminator": { - "propertyName": "type" - } - }, - "Address": { - "type": "string", - "description": "An alphanumeric string representing a blockchain address. Will be in different formats for different chains. It is important to preserve the exact formatting and capitalization of the address.", - "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" - }, - "AddressTag": { - "type": "string", - "description": "The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.", - "nullable": true, - "example": "123456789" - }, - "TransferDestinationBlockchainLocation": { - "description": "A destination blockchain address.", - "type": "object", - "required": [ - "type", - "chain", - "address" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "blockchain" - ] - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "addressTag": { - "$ref": "#/components/schemas/AddressTag" - }, - "chain": { - "$ref": "#/components/schemas/Chain" - } - } - }, - "TransferDestinationWalletLocation": { - "description": "A destination wallet location.", - "type": "object", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "wallet" - ] - }, - "id": { - "type": "string", - "description": "The id of the wallet.", - "example": "12345" - }, "address": { "type": "string", - "description": "An alphanumeric string which indicates the wallet address used to receive the transfer. Will only be set when the transfer source is a blockchain address.", "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" - }, - "addressTag": { - "$ref": "#/components/schemas/AddressTag" - } - } - }, - "TransferDestinationLocation": { - "description": "A destination of funds.", - "oneOf": [ - { - "$ref": "#/components/schemas/TransferDestinationBlockchainLocation" - }, - { - "$ref": "#/components/schemas/TransferDestinationWalletLocation" } - ], - "discriminator": { - "propertyName": "type" } }, - "Money": { + "PaymentIntentFees": { "type": "object", "required": [ + "type", "amount", "currency" ], "properties": { - "amount": { - "type": "string", - "description": "Magnitude of the amount, in units of the currency, with a `.`.", - "example": "3.14" - }, - "currency": { + "type": { "type": "string", - "description": "Currency code for the amount.", "enum": [ - "USD", - "EUR", - "BTC", - "ETH" + "blockchainLeaseFee", + "totalPaymentFees" ] - } - } - }, - "Fee": { - "type": "object", - "required": [ - "amount", - "currency", - "type" - ], - "properties": { + }, "amount": { + "description": "Magnitude of the amount, in units of the currency, with a `.`.", "type": "string", - "description": "Magnitude of the fee amount, in units of the currency, with a `.`.", - "example": "10.00" + "example": "3.14" }, "currency": { + "description": "Currency code.", "type": "string", - "description": "Currency code for the amount.", "enum": [ "USD" ] - }, - "type": { - "type": "string", - "description": "Category of the fee.", - "enum": [ - "network" - ] } } }, - "TransferErrorCode": { - "type": "string", - "description": "Indicates the failure reason of a transfer. Only present for transfers in a `failed` state. Possible values are `insufficient_funds`, `blockchain_error` and `transfer_denied` and `transfer_failed`", - "nullable": true, - "enum": [ - "transfer_failed", - "transfer_denied", - "blockchain_error", - "insufficient_funds" - ] - }, - "Transfer": { + "Timeline": { "type": "object", - "description": "A transfer of funds.", "required": [ - "id", - "source", - "destination", - "amount", - "status" + "status", + "time" ], "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "source": { - "$ref": "#/components/schemas/TransferSourceLocation" - }, - "destination": { - "$ref": "#/components/schemas/TransferDestinationLocation" - }, - "amount": { - "$ref": "#/components/schemas/Money" - }, - "fees": { - "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, - "type": "array", - "items": { - "$ref": "#/components/schemas/Fee" - } - }, - "transactionHash": { - "description": "A hash that uniquely identifies the onchain transaction. This is only available where either source or destination are of type blockchain.", - "type": "string", - "example": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63" - }, "status": { - "description": "Status of the transfer. Status `pending` indicates that the transfer is in the process of running; `complete` indicates it finished successfully; `failed` indicates it failed.", "type": "string", "enum": [ + "created", "pending", "complete", + "expired", "failed" ] }, - "errorCode": { - "$ref": "#/components/schemas/TransferErrorCode" + "context": { + "type": "string", + "enum": [ + "underpaid", + "paid", + "overpaid" + ] }, - "createDate": { - "description": "The create date of the transfer.", + "time": { + "description": "ISO-8601 UTC date/time format.", "type": "string", "format": "date-time" } } }, - "TransferDetailedTransfer": { + "PaymentIntent": { "type": "object", - "description": "A transfer of funds.", "required": [ - "id", - "source", - "destination", + "idempotencyKey", "amount", - "status" + "settlementCurrency", + "paymentMethods" ], "properties": { "id": { - "$ref": "#/components/schemas/Id" + "type": "string", + "description": "Unique system generated identifier for the entity.", + "format": "uuid", + "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, - "source": { - "$ref": "#/components/schemas/TransferSourceLocation" + "amount": { + "$ref": "#/components/schemas/CryptoPaymentsMoney" + }, + "amountPaid": { + "description": "Sum of the the amount paid.", + "type": "object", + "required": [ + "amount", + "currency" + ], + "properties": { + "amount": { + "description": "Magnitude of the amount, in units of the currency, with a `.`.", + "type": "string", + "example": "3.14" + }, + "currency": { + "description": "Currency code.", + "type": "string", + "enum": [ + "USD" + ] + } + } }, - "destination": { - "$ref": "#/components/schemas/TransferDestinationLocation" + "settlementCurrency": { + "description": "Desired currency for the payments to settle in.", + "type": "string", + "enum": [ + "USD", + "BTC", + "ETH" + ] }, - "amount": { - "$ref": "#/components/schemas/Money" + "paymentMethods": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentMethodBlockchain" + } }, "fees": { - "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, "type": "array", "items": { - "$ref": "#/components/schemas/Fee" + "$ref": "#/components/schemas/PaymentIntentFees" } }, - "transactionHash": { - "type": "string", - "description": "A hash that uniquely identifies the onchain transaction. This is only available where either source or destination are of type blockchain.", - "example": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63" + "paymentIds": { + "description": "List of associated payments.", + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "example": "69808f36-3e5e-4f37-bf82-ca79e4d70fc1" + } }, - "status": { - "type": "string", - "description": "Status of the transfer. Status `pending` indicates that the transfer is in the process of running; `complete` indicates it finished successfully; `failed` indicates it failed.", - "enum": [ - "failed", - "pending", - "complete" - ] + "timeline": { + "description": "State management timeline.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Timeline" + } }, - "errorCode": { - "$ref": "#/components/schemas/TransferErrorCode" + "expiresOn": { + "$ref": "#/components/schemas/UtcTimestamp" }, - "riskEvaluation": { - "$ref": "#/components/schemas/RiskEvaluation" + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" }, "createDate": { "$ref": "#/components/schemas/UtcTimestamp" } } }, - "Currency": { - "type": "string", - "description": "A currency associated with a balance or address.", - "nullable": true, - "enum": [ - "USD", - "EUR", - "BTC", - "ETH" - ] - }, - "AddressObject": { - "type": "object", - "properties": { - "address": { - "$ref": "#/components/schemas/Address" - }, - "addressTag": { - "$ref": "#/components/schemas/AddressTag" - }, - "currency": { - "$ref": "#/components/schemas/Currency" - }, - "chain": { - "$ref": "#/components/schemas/Chain" - } - } - }, - "GenerateAddressRequest": { - "type": "object", - "required": [ - "idempotencyKey", - "currency", - "chain" - ], - "properties": { - "idempotencyKey": { - "$ref": "#/components/schemas/IdempotencyKey" - }, - "currency": { - "$ref": "#/components/schemas/Currency" - }, - "chain": { - "$ref": "#/components/schemas/Chain" - } - } - }, "ExternalFiatAccountStatus": { "description": "Status of the account. A `pending` status indicates that the linking is in-progress; `complete` indicates the account was linked successfully; `failed` indicates it failed.", "type": "string", @@ -5315,6 +5192,16 @@ "description": "The country code of the issuer bank. Follows the ISO 3166-1 alpha-2 standard.", "example": "US" }, + "fundingType": { + "description": "The funding type of the card. Possible values are `credit`, `debit`, `prepaid`, and `unknown`.", + "type": "string", + "enum": [ + "credit", + "debit", + "prepaid", + "unknown" + ] + }, "fingerprint": { "$ref": "#/components/schemas/Fingerprint" }, @@ -5599,6 +5486,254 @@ } } }, + "ApplePayTokenEcHeader": { + "type": "object", + "required": [ + "ephemeralPublicKey", + "publicKeyHash", + "transactionId" + ], + "properties": { + "applicationData": { + "description": "Optional. Hash of the applicationData property of the original PKPaymentRequest object. If the value of that property is null, this key is omitted.", + "type": "string", + "example": "" + }, + "ephemeralPublicKey": { + "description": "Ephemeral public key bytes.", + "type": "string", + "example": "MFkwEwYHKoZIzj.../zlsw==" + }, + "publicKeyHash": { + "description": "Hash of the X.509 encoded public key bytes of the merchant’s certificate.", + "type": "string", + "example": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=" + }, + "transactionId": { + "description": "Transaction identifier, generated on the device.", + "type": "string", + "example": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4" + } + } + }, + "ApplePayTokenRsaHeader": { + "type": "object", + "required": [ + "wrappedKey", + "publicKeyHash", + "transactionId" + ], + "properties": { + "applicationData": { + "description": "Optional. Hash of the applicationData property of the original PKPaymentRequest object. If the value of that property is null, this key is omitted.", + "type": "string" + }, + "wrappedKey": { + "description": "The symmetric key wrapped using your RSA public key.", + "type": "string" + }, + "publicKeyHash": { + "description": "Hash of the X.509 encoded public key bytes of the merchant’s certificate.", + "type": "string" + }, + "transactionId": { + "description": "Transaction identifier, generated on the device.", + "type": "string" + } + } + }, + "ApplePayToken": { + "type": "object", + "required": [ + "version", + "data", + "signature", + "header" + ], + "properties": { + "version": { + "description": "ApplePay token version information.", + "type": "string", + "enum": [ + "EC_v1", + "RSA_v1" + ] + }, + "data": { + "description": "Encrypted payment data. Base64 encoded as a string.", + "type": "string", + "example": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+...T6Ms7PhiNZpuGEE2QE=" + }, + "signature": { + "description": "Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.", + "type": "string", + "example": "MIAGCSqGSIb3DQEHAqCAMIACAQEx.../WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=" + }, + "header": { + "description": "Additional version-dependent information used to decrypt and verify the payment.", + "oneOf": [ + { + "$ref": "#/components/schemas/ApplePayTokenEcHeader" + }, + { + "$ref": "#/components/schemas/ApplePayTokenRsaHeader" + } + ] + } + } + }, + "GooglePayToken": { + "type": "object", + "required": [ + "signature", + "protocolVersion", + "signedMessage" + ], + "properties": { + "signature": { + "description": "Verifies the message came from Google. The signature is created using ECDSA.", + "type": "string" + }, + "protocolVersion": { + "description": "Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0.", + "type": "string" + }, + "signedMessage": { + "description": "A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process, this value is serialized.", + "type": "string" + } + } + }, + "PaymentTokenRequest": { + "type": "object", + "required": [ + "idempotencyKey", + "type", + "tokenData" + ], + "properties": { + "idempotencyKey": { + "$ref": "#/components/schemas/IdempotencyKey" + }, + "type": { + "description": "Type of the digital wallet token.", + "type": "string", + "enum": [ + "applepay", + "googlepay" + ] + }, + "tokenData": { + "description": "The token data", + "oneOf": [ + { + "$ref": "#/components/schemas/ApplePayToken" + }, + { + "$ref": "#/components/schemas/GooglePayToken" + } + ] + } + } + }, + "TokenizedCardDetails": { + "type": "object", + "required": [ + "expMonth", + "expYear", + "last4", + "bin" + ], + "properties": { + "expMonth": { + "description": "The card's expiration month.", + "type": "integer", + "example": 1 + }, + "expYear": { + "description": "Four digit number representing the card's expiration year.", + "type": "integer", + "example": 2020 + }, + "network": { + "description": "The network of the card.", + "type": "string", + "enum": [ + "VISA", + "MASTERCARD", + "AMEX", + "UNKNOWN" + ] + }, + "last4": { + "description": "The last 4 digits of the card.", + "type": "string", + "example": "0123" + }, + "bin": { + "description": "The bank identification number (BIN), the first 6 digits of the card.", + "type": "string", + "example": "401230" + }, + "fundingType": { + "description": "The funding type of the card.", + "type": "string", + "enum": [ + "credit", + "debit", + "prepaid", + "unknown" + ] + }, + "issuerCountry": { + "description": "The country code of the issuer bank. Follows the ISO 3166-1 alpha-2 standard.", + "type": "string", + "example": "US" + } + } + }, + "PaymentToken": { + "type": "object", + "required": [ + "id", + "type", + "expiresOn", + "cardDetails", + "createDate", + "updateDate" + ], + "properties": { + "id": { + "description": "Unique system generated identifier for the digital wallet token.", + "type": "string", + "format": "uuid", + "example": "gc988ed5-c189-4f70-a074-e5beb7eb8e32" + }, + "type": { + "description": "Type of the digital wallet token.", + "type": "string", + "enum": [ + "applepay", + "googlepay" + ] + }, + "expiresOn": { + "description": "Datetime when the digital token expires. ISO-8601.", + "type": "string", + "format": "date-time", + "example": "2022-01-18T19:20:00Z" + }, + "cardDetails": { + "$ref": "#/components/schemas/TokenizedCardDetails" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, "BankAddress": { "type": "object", "description": "The address details for the bank, as provided during bank account creation.", @@ -6389,6 +6524,19 @@ "format": "uuid", "example": "fc988ed5-c129-4f70-a064-e5beb7eb8e32" }, + "ChargebackStatus": { + "type": "string", + "enum": [ + "active", + "resolved", + "pending", + "won", + "lost", + "canceled", + "closed" + ], + "description": "Enumerated status of the chargeback. `active` means you’ve received a dispute and you need to submit evidence if you want to defend against it. 'resolved' means the disputed payment had been refunded previously. Your account has not been debited. `pending` means we have acknowledged your evidence and forwarded it to the card issuer. `won` means you have won the dispute and your account has been credited. `lost` means the issuing bank has rejected your evidence and you have lost the dispute. There are no further financial implications. `canceled` means the issuing bank has canceled the dispute and your account has been credited. `closed` means the time to respond to this dispute has run out. No evidence can be submitted at this point." + }, "ChargebackCategories": { "type": "string", "description": "Enumerated category of the chargeback status codes based on the chargeback status code.", @@ -6452,6 +6600,7 @@ "id", "paymentId", "merchantId", + "status", "history", "reasonCode" ], @@ -6470,6 +6619,9 @@ "type": "string", "example": "10.4" }, + "status": { + "$ref": "#/components/schemas/ChargebackStatus" + }, "category": { "$ref": "#/components/schemas/ChargebackCategories" }, @@ -6546,6 +6698,30 @@ } } }, + "Money": { + "type": "object", + "required": [ + "amount", + "currency" + ], + "properties": { + "amount": { + "type": "string", + "description": "Magnitude of the amount, in units of the currency, with a `.`.", + "example": "3.14" + }, + "currency": { + "type": "string", + "description": "Currency code for the amount.", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH" + ] + } + } + }, "Balances": { "type": "object", "description": "Available and unsettled balances of the merchant.", diff --git a/openapi/json/payouts.json b/openapi/json/payouts.json index 782309d..6260689 100644 --- a/openapi/json/payouts.json +++ b/openapi/json/payouts.json @@ -2,105 +2,77 @@ "openapi": "3.0.2", "servers": [ { - "url": "api-sandbox.circle.com" + "url": "https://api-sandbox.circle.com" } ], "info": { - "version": "1.0.3", + "version": "1.1.0", "title": "Payouts API", - "description": "APIs for making payouts." + "description": "The Circle Payouts API allows you to programmatically make fast, global payouts to your customers, vendors, and suppliers. Use traditional methods like bank wires and ACH, or make payouts on supported blockchains." }, "tags": [ { - "name": "Payouts" + "name": "Payouts", + "description": "Create and get information on wire, ACH, SEPA and address book payouts." }, { - "name": "On-chain payouts" + "name": "Crypto Address Book", + "description": "Manage blockchain addresses with metadata." }, { - "name": "Wires" + "name": "Wires", + "description": "Create, get instructions, and get information on bank accounts for wire transfers." }, { - "name": "ACH" + "name": "ACH", + "description": "Link and get information on bank account for ACH payments." }, { - "name": "SEPA" + "name": "SEPA", + "description": "Create and get information on SEPA accounts." }, { - "name": "Returns" + "name": "Returns", + "description": "Get information on returned payouts." + }, + { + "name": "Crypto Exchange Rates", + "description": "Pull estimated exchange rate for crypto currencies." } ], "paths": { "/v1/payouts": { - "get": { + "post": { "security": [ { "bearerAuth": [] } ], - "parameters": [ - { - "name": "source", - "description": "Universally unique identifier (UUID v4) for the source wallet. Filters the results to fetch all payouts made from a source wallet. If not provided, payouts from all wallets will be returned.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "format": "uuid", - "example": "54c1cbab-c419-450f-ad23-906fa03af7f0" - } - }, - { - "name": "type", - "description": "Destination bank account type. Filters the results to fetch all payouts made to a specified destination bank account type. This query parameter can be passed multiple times to fetch results matching multiple destination bank account types.", - "in": "query", - "required": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PayoutDestinationType" - } - } - }, - { - "name": "status", - "description": "Queries items with the specified status. Matches any status if unspecified.", - "in": "query", - "required": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PayoutStatus" - } - } - }, - { - "$ref": "#/components/parameters/Destination" - }, - { - "$ref": "#/components/parameters/From" - }, - { - "$ref": "#/components/parameters/To" - }, - { - "$ref": "#/components/parameters/PageBefore" - }, - { - "$ref": "#/components/parameters/PageAfter" - }, - { - "$ref": "#/components/parameters/PageSize" - } - ], - "summary": "List all payouts", - "operationId": "listPayouts", + "summary": "Create a payout", + "description": "\nCreate a wire, ACH, SEPA or crypto payout. \n\nThe following table includes the supported pairs of amount.currency and toAmount.currency for address book payouts:\n\n| amount.currency | toAmount.currency |\n| ---------------- | ------------ |\n| USD | USD |\n| USD | BTC |\n| USD | ETH |\n| USD | MTC |\n| EUR | EUR |\n| BTC | USD |\n| BTC | BTC |\n| ETH | USD |\n| ETH | ETH |\n", + "operationId": "createPayout", "tags": [ "Payouts" ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/FiatPayoutCreationRequest" + }, + { + "$ref": "#/components/schemas/CryptoPayoutCreationRequest" + } + ] + } + } + } + }, "responses": { - "200": { - "description": "Successfully retrieved a list of payouts.", + "201": { + "description": "Successfully created a payout.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -109,18 +81,22 @@ "content": { "application/json": { "schema": { - "title": "ListPayoutsResponse", + "title": "CreatePayoutResponse", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Payout" - } + "oneOf": [ + { + "$ref": "#/components/schemas/FiatPayout" + }, + { + "$ref": "#/components/schemas/CryptoPayout" + } + ] } } }, "examples": { - "response": { + "Fiat Payout": { "value": { "data": [ { @@ -135,6 +111,10 @@ "amount": "3.14", "currency": "USD" }, + "toAmount": { + "amount": "3.14", + "currency": "EUR" + }, "fees": { "amount": "3.14", "currency": "USD" @@ -177,39 +157,168 @@ } ] } + }, + "Crypto Payout": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "address_book", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "toAmount": { + "amount": "3.14", + "currency": "ETH" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "errorCode": "transaction_denied", + "riskEvaluation": { + "decision": "denied", + "reason": "4000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } } } } } }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, - "post": { + "get": { "security": [ { "bearerAuth": [] } ], - "summary": "Create a payout", - "operationId": "createPayout", - "tags": [ - "Payouts" - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PayoutCreationRequest" + "parameters": [ + { + "name": "source", + "description": "Identifier for the source wallet. Filters the fetched payout results to only be from a specific source wallet. If not provided, payouts from all wallets will be returned.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "example": "1000565227" + } + }, + { + "name": "destination", + "description": "Universally unique identifier (UUID v4) for the destination. Filters the fetched payout results made to a specific destination. If not provided, payouts to all destinations will be returned.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uuid", + "example": "54c1cbab-c419-450f-ad23-906fa03af7f0" + } + }, + { + "name": "type", + "description": "Destination type. Filters the results to fetch all payouts made to a specified destination type. This query parameter can be passed multiple times to fetch results matching multiple destination types. The address_book destination type cannot be combined with other types.", + "in": "query", + "required": false, + "schema": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/components/schemas/PayoutDestinationType" + } + } + }, + { + "name": "status", + "description": "Queries items with the specified status. Matches any status if unspecified.", + "in": "query", + "required": false, + "schema": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/components/schemas/PayoutStatus" } } + }, + { + "name": "sourceCurrency", + "description": "Queries items with the specified source currency `amount.currency`. Matches any source currency if unspecified.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC", + "FLW", + "MAN" + ] + } + }, + { + "name": "destinationCurrency", + "description": "Queries items with the specified destination currency `toAmount.currency`. Matches any destination currency if unspecified.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC", + "FLW", + "MAN" + ] + } + }, + { + "$ref": "#/components/parameters/Chain" + }, + { + "$ref": "#/components/parameters/From" + }, + { + "$ref": "#/components/parameters/To" + }, + { + "$ref": "#/components/parameters/PageBefore" + }, + { + "$ref": "#/components/parameters/PageAfter" + }, + { + "$ref": "#/components/parameters/PageSize" } - }, + ], + "summary": "List all payouts", + "operationId": "listPayouts", + "tags": [ + "Payouts" + ], "responses": { - "201": { - "description": "Successfully created a payout.", + "200": { + "description": "Successfully retrieved a list of payouts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -218,15 +327,25 @@ "content": { "application/json": { "schema": { - "title": "CreatePayoutResponse", + "title": "ListPayoutsResponse", "properties": { "data": { - "$ref": "#/components/schemas/Payout" + "type": "array", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/FiatPayout" + }, + { + "$ref": "#/components/schemas/CryptoPayout" + } + ] + } } } }, "examples": { - "response": { + "Fiat Payout": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", @@ -240,6 +359,10 @@ "amount": "3.14", "currency": "USD" }, + "toAmount": { + "amount": "3.14", + "currency": "EUR" + }, "fees": { "amount": "3.14", "currency": "USD" @@ -281,14 +404,45 @@ "updateDate": "2020-04-10T02:13:30.000Z" } } + }, + "Crypto Payout": { + "value": { + "data": [ + { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "address_book", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "toAmount": { + "amount": "3.14", + "currency": "ETH" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "errorCode": "transaction_denied", + "riskEvaluation": { + "decision": "denied", + "reason": "4000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + ] + } } } } } }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, "401": { "$ref": "#/components/responses/NotAuthorized" } @@ -326,12 +480,19 @@ "title": "GetPayoutResponse", "properties": { "data": { - "$ref": "#/components/schemas/DetailedPayout" + "oneOf": [ + { + "$ref": "#/components/schemas/FiatDetailedPayout" + }, + { + "$ref": "#/components/schemas/CryptoPayout" + } + ] } } }, "examples": { - "response": { + "Fiat Payout": { "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", @@ -345,6 +506,10 @@ "amount": "3.14", "currency": "USD" }, + "toAmount": { + "amount": "3.14", + "currency": "EUR" + }, "fees": { "amount": "3.14", "currency": "USD" @@ -387,6 +552,38 @@ "updateDate": "2020-04-10T02:13:30.000Z" } } + }, + "Crypto Payout": { + "value": { + "data": { + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", + "sourceWalletId": "53535335", + "destination": { + "type": "address_book", + "id": "b8627ae8-732b-4d25-b947-1df8f4007a29" + }, + "amount": { + "amount": "3.14", + "currency": "USD" + }, + "toAmount": { + "amount": "3.14", + "currency": "ETH" + }, + "fees": { + "amount": "3.14", + "currency": "USD" + }, + "status": "pending", + "errorCode": "transaction_denied", + "riskEvaluation": { + "decision": "denied", + "reason": "4000" + }, + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" + } + } } } } @@ -401,97 +598,42 @@ } } }, - "/v1/transfers": { + "/v1/addressBook/recipients": { "post": { "security": [ { "bearerAuth": [] } ], - "summary": "Create a transfer", - "description": "A transfer can be made from an existing funded wallet to a blockchain address or another wallet.", - "operationId": "createTransfer", + "summary": "Create a recipient", + "operationId": "createAddressBookRecipient", "tags": [ - "On-chain payouts" + "Crypto Address Book" ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/TransferCreationRequest" - }, - "examples": { - "request": { - "value": { - "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", - "source": { - "type": "wallet", - "id": "12345" - }, - "destination": { - "type": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, - "amount": { - "amount": "3.14", - "currency": "USD" - } - } - }, - "travel rule": { - "value": { - "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": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, - "amount": { - "amount": "3000.00", - "currency": "USD" - } - } - } + "$ref": "#/components/schemas/AddressBookRecipientRequest" } } } }, "responses": { "201": { + "description": "Successfully created an address book recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, - "description": "Successfully created a transfer.", "content": { "application/json": { "schema": { - "title": "CreateTransferResponse", + "title": "CreateAddressBookRecipientResponse", "properties": { "data": { - "$ref": "#/components/schemas/Transfer" + "$ref": "#/components/schemas/AddressBookRecipient" } } }, @@ -499,68 +641,29 @@ "response": { "value": { "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "source": { - "type": "wallet", - "id": "12345" - }, - "destination": { - "type": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - } - } - }, - "travel rule": { - "value": { - "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "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": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, - "amount": { - "amount": "3000.00", - "currency": "USD" + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", + "chain": "ETH", + "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" + "createDate": "2022-07-21T20:13:35.578678Z", + "updateDate": "2022-07-21T20:19:24.859052Z" } } } } } } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" } } }, @@ -570,39 +673,53 @@ "bearerAuth": [] } ], + "summary": "List all recipients", + "operationId": "listAddressBookRecipients", + "tags": [ + "Crypto Address Book" + ], "parameters": [ { - "name": "walletId", - "description": "Unique identifier for the source or destination wallet of transfers, if any. May not be used in conjunction with destinationWalletId or sourceWalletId. Useful for fetching all transfers related to a wallet.", + "name": "address", + "description": "Filters results to fetch only address book recipients with the provided address.", "in": "query", "required": false, "schema": { - "type": "string", - "example": "12345" + "type": "string" } }, { - "name": "sourceWalletId", - "description": "Unique identifier for the source wallet of transfers, if any.", + "name": "chain", + "description": "Filters results to fetch only address book recipients with the provided chain.", "in": "query", "required": false, "schema": { - "type": "string", - "example": "12345" + "type": "string" } }, { - "name": "destinationWalletId", - "description": "Unique identifier for the destination wallet of transfers, if any.", + "name": "email", + "description": "Filters results to fetch only address book recipients that have the provided email in their metadata.", "in": "query", "required": false, "schema": { - "type": "string", - "example": "12345" + "type": "string" } }, { - "$ref": "#/components/parameters/ReturnIdentities" + "name": "status", + "description": "Filters results to fetch only address book recipients that have the provided status.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "inactive", + "active", + "denied" + ] + } }, { "$ref": "#/components/parameters/From" @@ -620,15 +737,9 @@ "$ref": "#/components/parameters/PageSize" } ], - "summary": "List all transfers", - "description": "Searches for transfers involving the provided wallets. If no wallet ids are provided, searches all wallets associated with your Circle API account. If the date parameters are omitted, returns the most recent transfers. This endpoint returns up to 50 transfers in descending chronological order or pageSize, if provided.", - "operationId": "listTransfers", - "tags": [ - "On-chain payouts" - ], "responses": { "200": { - "description": "Successfully retrieved a list of transfers.", + "description": "Successfully retrieved a list of address book recipients.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" @@ -637,12 +748,12 @@ "content": { "application/json": { "schema": { - "title": "ListTransfersResponse", + "title": "ListAddressBookRecipientsResponse", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Transfer" + "$ref": "#/components/schemas/AddressBookRecipient" } } } @@ -653,65 +764,17 @@ "data": [ { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "source": { - "type": "wallet", - "id": "12345" - }, - "destination": { - "type": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "addressTag": "123456789", - "chain": "ALGO" - }, - "amount": { - "amount": "3.14", - "currency": "USD" - }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", - "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" - } - ] - } - }, - "travel rule": { - "value": { - "data": [ - { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "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": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "addressTag": "123456789", - "chain": "ALGO" - }, - "amount": { - "amount": "3000.00", - "currency": "USD" + "chain": "ALGO", + "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", + "addressTag": "123456789", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" } ] } @@ -726,14 +789,11 @@ } } }, - "/v1/transfers/{id}": { + "/v1/addressBook/recipients/{id}": { "get": { "parameters": [ { "$ref": "#/components/parameters/IdPath" - }, - { - "$ref": "#/components/parameters/ReturnIdentities" } ], "security": [ @@ -741,26 +801,26 @@ "bearerAuth": [] } ], - "summary": "Get a transfer", - "operationId": "getTransfer", + "summary": "Get a recipient", + "operationId": "getAddressBookRecipient", "tags": [ - "On-chain payouts" + "Crypto Address Book" ], "responses": { "200": { + "description": "Successfully retrieved an address book recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, - "description": "Successfully retrieved a transfer.", "content": { "application/json": { "schema": { - "title": "GetTransferResponse", + "title": "GetAddressBookRecipientResponse", "properties": { "data": { - "$ref": "#/components/schemas/TransferDetailedTransfer" + "$ref": "#/components/schemas/AddressBookRecipient" } } }, @@ -769,67 +829,141 @@ "value": { "data": { "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "source": { - "type": "wallet", - "id": "12345" - }, - "destination": { - "type": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, - "amount": { - "amount": "3.14", - "currency": "USD" + "chain": "ALGO", + "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", + "addressTag": "123456789", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" + "createDate": "2020-04-10T02:13:30.000Z", + "updateDate": "2020-04-10T02:13:30.000Z" } } - }, - "travel rule": { + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + }, + "patch": { + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Modify a recipient", + "operationId": "modifyAddressBookRecipient", + "tags": [ + "Crypto Address Book" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressBookRecipientModifyRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully updated the address book recipient.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "ModifyAddressBookRecipientResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/AddressBookRecipient" + } + } + }, + "examples": { + "response": { "value": { "data": { - "id": "b8627ae8-732b-4d25-b947-1df8f4007a29", - "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": "blockchain", - "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", - "chain": "ETH" - }, - "amount": { - "amount": "3000.00", - "currency": "USD" + "id": "8755d0ea-14f9-4259-b092-de23c14b6568", + "chain": "ETH", + "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3", + "metadata": { + "nickname": "sample nickname", + "email": "satoshi@circle.com", + "bns": "sample.circle" }, - "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63", "status": "pending", - "createDate": "2020-04-10T02:13:30.000Z" + "createDate": "2022-07-21T20:13:35.578678Z", + "updateDate": "2022-07-21T20:19:24.859052Z" } } } } } } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + }, + "delete": { + "parameters": [ + { + "$ref": "#/components/parameters/IdPath" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Delete a recipient", + "operationId": "deleteAddressBookRecipient", + "tags": [ + "Crypto Address Book" + ], + "responses": { + "200": { + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "description": "Successfully removed the address book recipient." + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" } } } @@ -1211,7 +1345,7 @@ "content": { "application/json": { "schema": { - "title": "CreateAchAccountResponse", + "title": "CreateMockAchAccountResponse", "properties": { "data": { "$ref": "#/components/schemas/MockAchAccountResponse" @@ -1488,6 +1622,75 @@ } } } + }, + "/v1/exchange/rates/{trading-pair}": { + "get": { + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Get a exchange rate", + "description": "Fetch the current rates for the specified trading pair. The trading pair is defined by a base currency followed by a quote currency. The response contains buy and sell rates denominated in the quote currency. **Exchange rate is an estimate only and is subject to change by the time you submit the actual request.**", + "operationId": "getExchangeRates", + "tags": [ + "Crypto Exchange Rates" + ], + "parameters": [ + { + "name": "trading-pair", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "BTC-USD", + "ETH-USD", + "FLOW-USD" + ] + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved rates.", + "headers": { + "X-Request-Id": { + "$ref": "#/components/headers/XRequestId" + } + }, + "content": { + "application/json": { + "schema": { + "title": "GetExchangeRatesResponse", + "properties": { + "data": { + "$ref": "#/components/schemas/Rate" + } + } + }, + "examples": { + "response": { + "value": { + "data": { + "buy": "46317.59000", + "sell": "45400.41000", + "createDate": "2020-04-10T02:13:30.000Z" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/NotAuthorized" + } + } + } } }, "components": { @@ -1500,11 +1703,12 @@ "schemas": { "PayoutDestinationType": { "type": "string", - "description": "The destination bank account type.", + "description": "The destination type.", "enum": [ "wire", "ach", - "sepa" + "sepa", + "address_book" ] }, "PayoutStatus": { @@ -1522,16 +1726,25 @@ "format": "uuid", "example": "b8627ae8-732b-4d25-b947-1df8f4007a29" }, - "BankDestination": { + "FiatPayoutDestinationType": { + "type": "string", + "description": "The destination type.", + "enum": [ + "wire", + "ach", + "sepa" + ] + }, + "FiatPayoutDestination": { "type": "object", - "description": "The destination bank account.", + "description": "The destination.", "required": [ "type", "id" ], "properties": { "type": { - "$ref": "#/components/schemas/PayoutDestinationType" + "$ref": "#/components/schemas/FiatPayoutDestinationType" }, "id": { "$ref": "#/components/schemas/Id" @@ -1539,7 +1752,6 @@ "name": { "type": "string", "description": "Bank name plus last four digits of the bank account number or IBAN.", - "readOnly": true, "example": "COMMERZBANK AG ****3000" } } @@ -1565,6 +1777,33 @@ } } }, + "PayoutMoney": { + "type": "object", + "required": [ + "amount", + "currency" + ], + "properties": { + "amount": { + "type": "string", + "description": "Magnitude of the amount, in units of the currency, with a `.`.", + "example": "3.14" + }, + "currency": { + "type": "string", + "description": "Currency code for the amount.", + "enum": [ + "USD", + "EUR", + "BTC", + "ETH", + "MTC", + "FLW", + "MAN" + ] + } + } + }, "PayoutErrorCode": { "type": "string", "nullable": true, @@ -1667,7 +1906,7 @@ } } }, - "Payout": { + "FiatPayout": { "type": "object", "properties": { "id": { @@ -1679,11 +1918,14 @@ "example": "53535335" }, "destination": { - "$ref": "#/components/schemas/BankDestination" + "$ref": "#/components/schemas/FiatPayoutDestination" }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" }, + "toAmount": { + "$ref": "#/components/schemas/PayoutMoney" + }, "fees": { "$ref": "#/components/schemas/FiatMoneyUsd" }, @@ -1715,6 +1957,69 @@ } } }, + "CryptoPayoutDestinationType": { + "type": "string", + "description": "The destination type.", + "enum": [ + "address_book" + ] + }, + "CryptoPayoutDestination": { + "type": "object", + "description": "The destination.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/CryptoPayoutDestinationType" + }, + "id": { + "$ref": "#/components/schemas/Id" + } + } + }, + "CryptoPayout": { + "type": "object", + "properties": { + "id": { + "$ref": "#/components/schemas/Id" + }, + "sourceWalletId": { + "type": "string", + "description": "The identifier of the source wallet used to fund a payout.", + "example": "53535335" + }, + "destination": { + "$ref": "#/components/schemas/CryptoPayoutDestination" + }, + "amount": { + "$ref": "#/components/schemas/PayoutMoney" + }, + "toAmount": { + "$ref": "#/components/schemas/PayoutMoney" + }, + "fees": { + "$ref": "#/components/schemas/PayoutMoney" + }, + "status": { + "$ref": "#/components/schemas/PayoutStatus" + }, + "errorCode": { + "$ref": "#/components/schemas/PayoutErrorCode" + }, + "riskEvaluation": { + "$ref": "#/components/schemas/RiskEvaluation" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } + }, "IdempotencyKey": { "type": "string", "description": "Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.", @@ -1759,7 +2064,7 @@ } } }, - "PayoutCreationRequest": { + "FiatPayoutCreationRequest": { "type": "object", "required": [ "idempotencyKey", @@ -1775,7 +2080,20 @@ "$ref": "#/components/schemas/WalletLocation" }, "destination": { - "$ref": "#/components/schemas/BankDestination" + "type": "object", + "description": "The destination.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/FiatPayoutDestinationType" + }, + "id": { + "$ref": "#/components/schemas/Id" + } + } }, "amount": { "$ref": "#/components/schemas/FiatMoneyUsd" @@ -1785,68 +2103,6 @@ } } }, - "ExternalRef": { - "type": "string", - "description": "External network identifier which will be present once provided from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability Data (IMAD/OMAD)**: unique number given to each FedWire payment when using the Federal Reserve Bank Service which can be used to investigate and track wire transfers.\n", - "example": "YYYYMMDDXXXXXXXX012345" - }, - "DetailedPayout": { - "type": "object", - "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "sourceWalletId": { - "description": "The identifier of the source wallet used to fund a payout.", - "type": "string", - "example": "53535335" - }, - "destination": { - "$ref": "#/components/schemas/BankDestination" - }, - "amount": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "fees": { - "$ref": "#/components/schemas/FiatMoneyUsd" - }, - "status": { - "description": "Status of the payout. Status `pending` indicates that the payout is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", - "type": "string", - "enum": [ - "pending", - "complete", - "failed" - ] - }, - "trackingRef": { - "description": "A payout tracking reference. Will be present once known.", - "nullable": true, - "example": "CIR-6ESOQANEP3NAO" - }, - "externalRef": { - "$ref": "#/components/schemas/ExternalRef" - }, - "errorCode": { - "$ref": "#/components/schemas/PayoutErrorCode" - }, - "riskEvaluation": { - "$ref": "#/components/schemas/RiskEvaluation" - }, - "adjustments": { - "$ref": "#/components/schemas/FinalAdjustments" - }, - "return": { - "$ref": "#/components/schemas/UnwithdrawalObject" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" - }, - "updateDate": { - "$ref": "#/components/schemas/UtcTimestamp" - } - } - }, "IdentityAddress": { "type": "object", "required": [ @@ -1919,134 +2175,15 @@ "maxLength": 1024 }, "addresses": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentityAddress" - } - } - } - }, - "TransferSourceWalletLocation": { - "description": "A source wallet location.", - "type": "object", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "wallet" - ] - }, - "id": { - "type": "string", - "description": "The id of the wallet.", - "example": "12345" - }, - "identities": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Identity" - } - } - } - }, - "Chain": { - "type": "string", - "description": "A blockchain that a given currency is available on.", - "enum": [ - "ALGO", - "AVAX", - "BTC", - "ETH", - "FLOW", - "HBAR", - "MATIC", - "SOL", - "TRX", - "XLM" - ] - }, - "TransferSourceBlockchainLocation": { - "description": "A source blockchain address.", - "type": "object", - "required": [ - "type", - "chain" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "blockchain" - ] - }, - "chain": { - "$ref": "#/components/schemas/Chain" - }, - "identities": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Identity" - } - } - } - }, - "TransferSourceLocation": { - "description": "A source of funds.", - "oneOf": [ - { - "$ref": "#/components/schemas/TransferSourceWalletLocation" - }, - { - "$ref": "#/components/schemas/TransferSourceBlockchainLocation" - } - ], - "discriminator": { - "propertyName": "type" - } - }, - "Address": { - "type": "string", - "description": "An alphanumeric string representing a blockchain address. Will be in different formats for different chains. It is important to preserve the exact formatting and capitalization of the address.", - "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" - }, - "AddressTag": { - "type": "string", - "description": "The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.", - "nullable": true, - "example": "123456789" - }, - "TransferDestinationBlockchainLocation": { - "description": "A destination blockchain address.", - "type": "object", - "required": [ - "type", - "chain", - "address" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "blockchain" - ] - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "addressTag": { - "$ref": "#/components/schemas/AddressTag" - }, - "chain": { - "$ref": "#/components/schemas/Chain" + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityAddress" + } } } }, - "TransferDestinationWalletLocation": { - "description": "A destination wallet location.", + "TransferSourceWalletLocation": { + "description": "A source wallet location.", "type": "object", "required": [ "type", @@ -2064,28 +2201,12 @@ "description": "The id of the wallet.", "example": "12345" }, - "address": { - "type": "string", - "description": "An alphanumeric string which indicates the wallet address used to receive the transfer. Will only be set when the transfer source is a blockchain address.", - "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" - }, - "addressTag": { - "$ref": "#/components/schemas/AddressTag" - } - } - }, - "TransferDestinationLocation": { - "description": "A destination of funds.", - "oneOf": [ - { - "$ref": "#/components/schemas/TransferDestinationBlockchainLocation" - }, - { - "$ref": "#/components/schemas/TransferDestinationWalletLocation" + "identities": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Identity" + } } - ], - "discriminator": { - "propertyName": "type" } }, "Money": { @@ -2112,84 +2233,80 @@ } } }, - "Fee": { + "ToAmount": { "type": "object", "required": [ - "amount", - "currency", - "type" + "currency" ], "properties": { - "amount": { - "type": "string", - "description": "Magnitude of the fee amount, in units of the currency, with a `.`.", - "example": "10.00" - }, "currency": { "type": "string", "description": "Currency code for the amount.", "enum": [ - "USD" - ] - }, - "type": { - "type": "string", - "description": "Category of the fee.", - "enum": [ - "network" + "USD", + "EUR", + "BTC", + "ETH", + "MTC" ] } } }, - "TransferErrorCode": { - "type": "string", - "description": "Indicates the failure reason of a transfer. Only present for transfers in a `failed` state. Possible values are `insufficient_funds`, `blockchain_error` and `transfer_denied` and `transfer_failed`", - "nullable": true, - "enum": [ - "transfer_failed", - "transfer_denied", - "blockchain_error", - "insufficient_funds" - ] - }, - "Transfer": { + "CryptoPayoutCreationRequest": { "type": "object", - "description": "A transfer of funds.", "required": [ - "id", - "source", + "idempotencyKey", "destination", - "amount", - "status" + "amount" ], "properties": { - "id": { - "$ref": "#/components/schemas/Id" + "idempotencyKey": { + "$ref": "#/components/schemas/IdempotencyKey" }, "source": { - "$ref": "#/components/schemas/TransferSourceLocation" + "$ref": "#/components/schemas/TransferSourceWalletLocation" }, "destination": { - "$ref": "#/components/schemas/TransferDestinationLocation" + "$ref": "#/components/schemas/CryptoPayoutDestination" }, "amount": { "$ref": "#/components/schemas/Money" }, - "fees": { - "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, - "type": "array", - "items": { - "$ref": "#/components/schemas/Fee" - } + "toAmount": { + "$ref": "#/components/schemas/ToAmount" + } + } + }, + "ExternalRef": { + "type": "string", + "description": "External network identifier which will be present once provided from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability Data (IMAD/OMAD)**: unique number given to each FedWire payment when using the Federal Reserve Bank Service which can be used to investigate and track wire transfers.\n", + "example": "YYYYMMDDXXXXXXXX012345" + }, + "FiatDetailedPayout": { + "type": "object", + "properties": { + "id": { + "$ref": "#/components/schemas/Id" }, - "transactionHash": { - "description": "A hash that uniquely identifies the onchain transaction. This is only available where either source or destination are of type blockchain.", + "sourceWalletId": { + "description": "The identifier of the source wallet used to fund a payout.", "type": "string", - "example": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63" + "example": "53535335" + }, + "destination": { + "$ref": "#/components/schemas/FiatPayoutDestination" + }, + "amount": { + "$ref": "#/components/schemas/FiatMoneyUsd" + }, + "toAmount": { + "$ref": "#/components/schemas/PayoutMoney" + }, + "fees": { + "$ref": "#/components/schemas/FiatMoneyUsd" }, "status": { - "description": "Status of the transfer. Status `pending` indicates that the transfer is in the process of running; `complete` indicates it finished successfully; `failed` indicates it failed.", + "description": "Status of the payout. Status `pending` indicates that the payout is in process; `complete` indicates it finished successfully; `failed` indicates it failed.", "type": "string", "enum": [ "pending", @@ -2197,152 +2314,151 @@ "failed" ] }, + "trackingRef": { + "description": "A payout tracking reference. Will be present once known.", + "nullable": true, + "example": "CIR-6ESOQANEP3NAO" + }, + "externalRef": { + "$ref": "#/components/schemas/ExternalRef" + }, "errorCode": { - "$ref": "#/components/schemas/TransferErrorCode" + "$ref": "#/components/schemas/PayoutErrorCode" + }, + "riskEvaluation": { + "$ref": "#/components/schemas/RiskEvaluation" + }, + "adjustments": { + "$ref": "#/components/schemas/FinalAdjustments" + }, + "return": { + "$ref": "#/components/schemas/UnwithdrawalObject" }, "createDate": { - "description": "The create date of the transfer.", - "type": "string", - "format": "date-time" + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" } } }, - "TransferRequestSourceWalletLocation": { + "Chain": { + "type": "string", + "description": "A blockchain that a given currency is available on.", + "enum": [ + "ALGO", + "AVAX", + "BTC", + "ETH", + "FLOW", + "HBAR", + "MATIC", + "SOL", + "TRX", + "XLM" + ] + }, + "Address": { + "type": "string", + "description": "An alphanumeric string representing a blockchain address. Will be in different formats for different chains. It is important to preserve the exact formatting and capitalization of the address.", + "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" + }, + "AddressTag": { + "type": "string", + "description": "The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.", + "nullable": true, + "example": "123456789" + }, + "AddressBookRecipientMetadata": { "type": "object", - "required": [ - "type", - "id" - ], "properties": { - "type": { + "nickname": { "type": "string", - "enum": [ - "wallet" - ] + "description": "Nickname related to the address.", + "example": "sample nickname" }, - "id": { - "type": "string", - "description": "The id of the wallet.", - "example": "12345" + "email": { + "$ref": "#/components/schemas/Email" }, - "identities": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Identity" - } + "bns": { + "type": "string", + "description": "Blockchain Name Service (e.g. ENS) domain for the address.", + "example": "sample.circle" } } }, - "TransferRequestBlockchainLocation": { + "AddressBookRecipient": { "type": "object", "required": [ - "type", + "chain", "address", - "chain" + "metadata" ], "properties": { - "type": { - "type": "string", - "enum": [ - "blockchain" - ] + "id": { + "$ref": "#/components/schemas/Id" + }, + "chain": { + "$ref": "#/components/schemas/Chain" }, "address": { - "type": "string", - "description": "The blockchain address.", - "example": "0x8381470ED67C3802402dbbFa0058E8871F017A6F" + "$ref": "#/components/schemas/Address" }, "addressTag": { "$ref": "#/components/schemas/AddressTag" }, - "chain": { - "$ref": "#/components/schemas/Chain" + "metadata": { + "$ref": "#/components/schemas/AddressBookRecipientMetadata" + }, + "status": { + "type": "string", + "description": "Status of the address book recipient.", + "enum": [ + "pending", + "inactive", + "active", + "denied" + ] + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + }, + "updateDate": { + "$ref": "#/components/schemas/UtcTimestamp" } } }, - "TransferCreationRequest": { + "AddressBookRecipientRequest": { "type": "object", "required": [ "idempotencyKey", - "source", - "destination", - "amount" + "chain", + "address", + "metadata" ], "properties": { "idempotencyKey": { "$ref": "#/components/schemas/IdempotencyKey" }, - "source": { - "$ref": "#/components/schemas/TransferRequestSourceWalletLocation" + "chain": { + "$ref": "#/components/schemas/Chain" }, - "destination": { - "oneOf": [ - { - "$ref": "#/components/schemas/TransferRequestBlockchainLocation" - }, - { - "$ref": "#/components/schemas/WalletLocation" - } - ] + "address": { + "$ref": "#/components/schemas/Address" }, - "amount": { - "$ref": "#/components/schemas/Money" + "addressTag": { + "$ref": "#/components/schemas/AddressTag" + }, + "metadata": { + "$ref": "#/components/schemas/AddressBookRecipientMetadata" } } }, - "TransferDetailedTransfer": { + "AddressBookRecipientModifyRequest": { "type": "object", - "description": "A transfer of funds.", - "required": [ - "id", - "source", - "destination", - "amount", - "status" - ], "properties": { - "id": { - "$ref": "#/components/schemas/Id" - }, - "source": { - "$ref": "#/components/schemas/TransferSourceLocation" - }, - "destination": { - "$ref": "#/components/schemas/TransferDestinationLocation" - }, - "amount": { - "$ref": "#/components/schemas/Money" - }, - "fees": { - "description": "An array of fees applied to a transaction. This is only available when there is at least one non-zero fee.", - "readOnly": true, - "type": "array", - "items": { - "$ref": "#/components/schemas/Fee" - } - }, - "transactionHash": { - "type": "string", - "description": "A hash that uniquely identifies the onchain transaction. This is only available where either source or destination are of type blockchain.", - "example": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63" - }, - "status": { - "type": "string", - "description": "Status of the transfer. Status `pending` indicates that the transfer is in the process of running; `complete` indicates it finished successfully; `failed` indicates it failed.", - "enum": [ - "failed", - "pending", - "complete" - ] - }, - "errorCode": { - "$ref": "#/components/schemas/TransferErrorCode" - }, - "riskEvaluation": { - "$ref": "#/components/schemas/RiskEvaluation" - }, - "createDate": { - "$ref": "#/components/schemas/UtcTimestamp" + "metadata": { + "$ref": "#/components/schemas/AddressBookRecipientMetadata" } } }, @@ -3055,18 +3171,51 @@ "$ref": "#/components/schemas/UtcTimestamp" } } + }, + "Rate": { + "type": "object", + "required": [ + "buy", + "sell", + "createDate" + ], + "properties": { + "buy": { + "type": "string", + "description": "The buy rate denominated in the quote currency of the trading pair.", + "example": "46317.59000" + }, + "sell": { + "type": "string", + "description": "The sell rate denominated in the quote currency of the trading pair.", + "example": "45400.41000" + }, + "createDate": { + "$ref": "#/components/schemas/UtcTimestamp" + } + } } }, "parameters": { - "Destination": { - "name": "destination", - "description": "Universally unique identifier (UUID v4) for the destination bank account. Filters the results to fetch all payouts made to a destination bank account.", + "Chain": { + "name": "chain", + "description": "Queries items with the specified chain. Matches any chain if unspecified", "in": "query", "required": false, "schema": { "type": "string", - "format": "uuid", - "example": "e3d0a838-d732-49d0-bf44-73a668e38973" + "enum": [ + "ALGO", + "AVAX", + "BTC", + "ETH", + "FLOW", + "HBAR", + "MATIC", + "SOL", + "TRX", + "XLM" + ] } }, "From": { @@ -3130,17 +3279,6 @@ "format": "uuid", "example": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0" } - }, - "ReturnIdentities": { - "name": "returnIdentities", - "description": "Specify if you would like to see identities in the response. Restricts maximum returned items to 5. By default returnIdentities is false, resulting in the response not returning `data.source.identities`.", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "example": "true", - "default": false - } } }, "headers": { diff --git a/openapi/yaml/account.yaml b/openapi/yaml/account.yaml index a52be6f..0e1d3e1 100644 --- a/openapi/yaml/account.yaml +++ b/openapi/yaml/account.yaml @@ -1,20 +1,36 @@ openapi: 3.0.2 servers: -- url: api-sandbox.circle.com +- url: https://api-sandbox.circle.com info: - version: 1.0.3 + version: 1.1.0 title: Core Functionality - description: APIs for managing your account balance. These endpoints are available - with all Circle APIs. + description: 'All of Circle''s APIs share a common set of core functionality that + lets you manage your Circle Account in a programmatic way. + + + With a Circle Account your business can deposit traditional money from 80+ countries + and seamlessly convert them into "digital currency dollars": USDC. You can then + use USDC for everyday payments and treasury flows. + + ' tags: - name: Balances + description: Get information on settled and unsettled balances. - name: Payouts + description: Create and get information on 1st party payouts. - name: Wires + description: Create, get instructions, and get information on 1st party bank accounts + for wire transfers. - name: Signet + description: Create and get information on Signet accounts. - name: SEN + description: Create and get information on SEN accounts. - name: Transfers + description: Create and get information on 1st party transfers. - name: Addresses + description: Generate and get information on blockchain addresses. - name: Deposits + description: Get information on 1st party deposits. paths: /v1/businessAccount/balances: get: @@ -51,60 +67,36 @@ paths: '401': $ref: '#/components/responses/NotAuthorized' /v1/businessAccount/payouts: - get: + post: security: - bearerAuth: [] - parameters: - - $ref: '#/components/parameters/Destination' - - name: type - description: Destination bank account type. Filters the results to fetch all - payouts made to a specified destination bank account type. This query parameter - can be passed multiple times to fetch results matching multiple destination - bank account types. - in: query - required: false - schema: - type: string - enum: - - wire - - name: status - description: Queries items with the specified status. Matches any status if - unspecified. - in: query - required: false - schema: - type: array - items: - $ref: '#/components/schemas/PayoutStatus' - - $ref: '#/components/parameters/From' - - $ref: '#/components/parameters/To' - - $ref: '#/components/parameters/PageBefore' - - $ref: '#/components/parameters/PageAfter' - - $ref: '#/components/parameters/PageSize' - summary: List all payouts - operationId: listBusinessPayouts + summary: Create a payout + operationId: createBusinessPayout tags: - Payouts + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BusinessPayoutCreationRequest' responses: - '200': - description: Successfully retrieved a list of payouts. + '201': + description: Successfully created a payout. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListBusinessPayoutsResponse + title: CreateBusinessPayoutResponse properties: data: - type: array - items: - $ref: '#/components/schemas/BusinessPayout' + $ref: '#/components/schemas/BusinessPayout' examples: response: value: data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + id: b8627ae8-732b-4d25-b947-1df8f4007a29 sourceWalletId: '53535335' destination: type: wire @@ -144,38 +136,65 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' - post: + get: security: - bearerAuth: [] - summary: Create a payout - operationId: createBusinessPayout + parameters: + - $ref: '#/components/parameters/Destination' + - name: type + description: Destination bank account type. Filters the results to fetch all + payouts made to a specified destination bank account type. This query parameter + can be passed multiple times to fetch results matching multiple destination + bank account types. + in: query + required: false + schema: + type: string + enum: + - wire + - name: status + description: Queries items with the specified status. Matches any status if + unspecified. + in: query + required: false + schema: + type: array + uniqueItems: true + items: + $ref: '#/components/schemas/PayoutStatus' + - $ref: '#/components/parameters/From' + - $ref: '#/components/parameters/To' + - $ref: '#/components/parameters/PageBefore' + - $ref: '#/components/parameters/PageAfter' + - $ref: '#/components/parameters/PageSize' + summary: List all payouts + operationId: listBusinessPayouts tags: - Payouts - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/BusinessPayoutCreationRequest' responses: - '201': - description: Successfully created a payout. + '200': + description: Successfully retrieved a list of payouts. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: CreateBusinessPayoutResponse + title: ListBusinessPayoutsResponse properties: data: - $ref: '#/components/schemas/BusinessPayout' + type: array + items: + $ref: '#/components/schemas/BusinessPayout' examples: response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 sourceWalletId: '53535335' destination: type: wire @@ -215,8 +234,6 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' - '400': - $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' /v1/businessAccount/payouts/{id}: @@ -1324,13 +1341,14 @@ components: description: Unique system generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 - PayoutDestinationType: + BusinessAccountPayoutDestinationType: type: string description: The destination bank account type. enum: - wire - ach - sepa + - signet BankDestination: type: object description: The destination bank account. @@ -1339,14 +1357,13 @@ components: - id properties: type: - $ref: '#/components/schemas/PayoutDestinationType' + $ref: '#/components/schemas/BusinessAccountPayoutDestinationType' id: $ref: '#/components/schemas/Id' name: type: string description: Bank name plus last four digits of the bank account number or IBAN. - readOnly: true example: COMMERZBANK AG ****3000 FiatMoney: type: object @@ -1517,6 +1534,7 @@ components: enum: - wire - sen + - signet id: $ref: '#/components/schemas/Id' BusinessPayoutCreationRequest: @@ -2270,7 +2288,6 @@ components: fees: description: An array of fees applied to a transaction. This is only available when there is at least one non-zero fee. - readOnly: true type: array items: $ref: '#/components/schemas/Fee' diff --git a/openapi/yaml/accounts.yaml b/openapi/yaml/accounts.yaml index 8a2735d..9fe4c5d 100644 --- a/openapi/yaml/accounts.yaml +++ b/openapi/yaml/accounts.yaml @@ -1,13 +1,19 @@ openapi: 3.0.2 servers: -- url: api-sandbox.circle.com +- url: https://api-sandbox.circle.com info: - version: 1.0.3 + version: 1.1.0 title: Accounts API - description: APIs to manage custodial wallets. + description: The Accounts API allows you to easily create and host digital wallets + for your customers, and manage transfers of funds across accounts- whether they + are within the Circle platform, or in / out of the platform via on-chain USDC, + EUROC, BTC, and ETH connectivity. tags: - name: Wallets + description: Create digital wallets and get information on their activity. - name: Transfers + description: Create transfers to another wallet or blockchain address, and get information + on those transfers. paths: /v1/wallets: post: @@ -984,7 +990,6 @@ components: fees: description: An array of fees applied to a transaction. This is only available when there is at least one non-zero fee. - readOnly: true type: array items: $ref: '#/components/schemas/Fee' @@ -1120,7 +1125,6 @@ components: fees: description: An array of fees applied to a transaction. This is only available when there is at least one non-zero fee. - readOnly: true type: array items: $ref: '#/components/schemas/Fee' diff --git a/openapi/yaml/circle-apis.yaml b/openapi/yaml/circle-apis.yaml index b5de251..5f06bcb 100644 --- a/openapi/yaml/circle-apis.yaml +++ b/openapi/yaml/circle-apis.yaml @@ -1,36 +1,69 @@ openapi: 3.0.2 servers: -- url: api-sandbox.circle.com +- url: https://api-sandbox.circle.com info: - version: 1.0.3 + version: 1.1.0 title: All Circle APIs - description: Circle's General, Core Functionality, Payments, Payouts, and Accounts - APIs bundled into one OpenAPI Specification. + description: Circle's General, Core Functionality, Payments, Payouts, Accounts, + and Crypto Payments APIs bundled into one OpenAPI Specification. tags: -- name: Health -- name: Management -- name: Encryption -- name: Subscriptions -- name: Stablecoins -- name: Channels -- name: Balances +- name: ACH + description: Link and get information on bank account for ACH payments. - name: Addresses + description: Generate and get information on blockchain addresses. +- name: Crypto Address Book + description: Manage blockchain addresses with metadata. +- name: Balances + description: Get information on settled and unsettled balances. - name: Cards -- name: Wires -- name: SEN -- name: SEPA -- name: ACH -- name: Signet + description: Link, update, and get information on debit/credit cards. +- name: Payment Tokens + description: Create Apple Pay and Google Pay payment tokens. +- name: Channels + description: View a list of channels. +- name: Chargebacks + description: Get information on card chargebacks. +- name: Crypto Payment Intents + description: Create and track intent for end user to pay via crypto. - name: Deposits -- name: Payment Intents + description: Get information on 1st party deposits. +- name: Encryption + description: Encrypt sensitive data. +- name: Crypto Exchange Rates + description: Pull estimated exchange rate for crypto currencies. +- name: Health + description: Inspect the health of the API. +- name: Management + description: General account and management information. - name: Payments -- name: Settlements -- name: Chargebacks -- name: Reversals + description: Get updates on whether user's crypto payment was received. - name: Payouts + description: Create and get information on wire, ACH, SEPA and address book payouts. - name: Returns -- name: Wallets + description: Get information on returned payouts. +- name: Reversals + description: Get information on ACH reversals. +- name: SEN + description: Create and get information on SEN accounts. +- name: SEPA + description: Create and get information on SEPA accounts. +- name: Settlements + description: Get information on settlement batches. +- name: Signet + description: Create and get information on Signet accounts. +- name: Stablecoins + description: Retrieve stablecoins and their respective names, symbols, circulating + total and per-chain amounts. +- name: Subscriptions + description: Manage subscriptions to notifications. - name: Transfers + description: Create transfers to another wallet or blockchain address, and get information + on those transfers. +- name: Wallets + description: Create digital wallets and get information on their activity. +- name: Wires + description: Create, get instructions, and get information on bank accounts for + wire transfers. paths: /ping: get: @@ -109,38 +142,6 @@ paths: keyId: key1 publicKey: LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWSBCTE9DSy0tLS0tClZlcnNpb246IEJDUEcgdjEuNTQKCm1RRU5CRjAxdmk0QkNBQ3JzMDNLS1Y0Qk9SRkYyT0Z4bUdvb0UyaTZMbnNneE5UL1dsV2s1ZTl2RDd2NENkSm0KcGJJbENmZ0U4WFlnYmhKUTE4YStaTzlPM0RFYUp2dGhJSEtjL0l1UEIvZmdEYUJUT285NkJzL2pVRFp6ZGxaVApQazNFUjliNFZPeGVwMFNPSHFMcmxTVFY4ZXB3M1R3SEdaL3NpSWdBYXEwRGdJdlZxUTY4TGVaMnorUFJWZm04CmhhSnJpb05SRU5Ja2ZNTWY5aFdySlowSW1zUk1aVmpDMVVrd2FSSHdrTTMwQUlia1dYcFJ5R205SXhQaXdGa08Kb1RnWlpwUFpsdVczckdkWER0NHZqL24za09hczV1dFdoNFovMlhjWHBiSUUyU0FPK0hycUdIclRnK1ZmZ05JNwpZcVZqYW5MOEN1bm83UkxmcDhKZlZDNXBLUm5ySVNCTnphN1ZBQkVCQUFHMEJrTnBjbU5zWllrQkhBUVFBUWtBCkJnVUNYVFcrTGdBS0NSQ3EzaHNwWjBMeGEwdnpCLzQvQTJpdk1CWW1aZXV2bEJZMm5ZZnNXek9Sb28vU3BIYkQKY2Y0UmtxZzZ0RERJSkUzNHhDVit0MzJydmJkM0ZOdVZseWs1MDVZRkpESnI4cVc2S0tkQVRXdU16eW5mMVVoUAo1M25hTlc0cXdrdSt3b0RWWjJpci9lUVI1WUc4L0RGcnd3bXdaa0dRd0Ftc3h5ZHd5anBnLzBrQ3lpZHkxdVBkCmVVWGgwdWt4dS9Dais4UFl5cHcwdit5V2tzbjdSZ2dVbkJFMWhiQ2pEV3FweHZjMEpDNVAxdmx6L2xRcWQrR3oKRC9Td1FJTVdRVElnV3BHRVVvQTRDc3drbU5PdHhsRVF1U0tueXNtTG02S0ExUmRhTzd6V2IrdWNLN21FZ2VoSwpXU2hHZExqRVNNZlVRUTczemNqMXg2amxLUFNhRlJyLzhXcHhrVXYzVHYvQzZMb0JpejRLCj1WSWg3Ci0tLS0tRU5EIFBHUCBQVUJMSUMgS0VZIEJMT0NLLS0tLS0K /v1/notifications/subscriptions: - get: - security: - - bearerAuth: [] - summary: List all notification subscriptions - description: Retrieve a list of existing notification subscriptions with details. - parameters: [] - operationId: listSubscriptions - tags: - - Subscriptions - responses: - '200': - description: Successfully retrieved a list of notification subscriptions. - content: - application/json: - schema: - title: ListSubscriptionsResponse - properties: - data: - type: array - items: - $ref: '#/components/schemas/SubscriptionResponse' - examples: - response: - value: - data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - endpoint: https://example.org/handler/for/notifications - subscriptionDetails: - - url: arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17 - status: confirmed - '401': - $ref: '#/components/responses/NotAuthorized' post: security: - bearerAuth: [] @@ -153,7 +154,7 @@ paths: requests will be rejected with a Limit Exceeded error. ' - operationId: createSubscribtion + operationId: createSubscription tags: - Subscriptions requestBody: @@ -167,7 +168,7 @@ paths: content: application/json: schema: - title: CreateSubscribtionResponse + title: CreateSubscriptionResponse properties: data: $ref: '#/components/schemas/SubscriptionResponse' @@ -186,6 +187,38 @@ paths: $ref: '#/components/responses/NotAuthorized' '429': $ref: '#/components/responses/LimitExceeded' + get: + security: + - bearerAuth: [] + summary: List all notification subscriptions + description: Retrieve a list of existing notification subscriptions with details. + parameters: [] + operationId: listSubscriptions + tags: + - Subscriptions + responses: + '200': + description: Successfully retrieved a list of notification subscriptions. + content: + application/json: + schema: + title: ListSubscriptionsResponse + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionResponse' + examples: + response: + value: + data: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + endpoint: https://example.org/handler/for/notifications + subscriptionDetails: + - url: arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17 + status: confirmed + '401': + $ref: '#/components/responses/NotAuthorized' /v1/notifications/subscriptions/{id}: delete: parameters: @@ -196,7 +229,7 @@ paths: description: To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed. - operationId: deleteSubscribtion + operationId: deleteSubscription tags: - Subscriptions responses: @@ -208,7 +241,7 @@ paths: content: application/json: schema: - title: DeleteSubscribtionResponse + title: DeleteSubscriptionResponse properties: data: $ref: '#/components/schemas/UnsubscribeResponse' @@ -459,6 +492,7 @@ paths: network: VISA bin: '401230' issuerCountry: US + fundingType: credit fingerprint: eb170539-9e1c-4e92-bf4f-1d09534fdca2 verification: avs: D @@ -592,6 +626,55 @@ paths: phoneNumber: '+14155555555' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + /v1/paymentTokens: + post: + security: + - bearerAuth: [] + summary: Create a payment token + description: Convert a digital wallet (Apple Pay, Google Pay) token to a single-use + payment token. + operationId: createPaymentToken + tags: + - Payment Tokens + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PaymentTokenRequest' + responses: + '201': + description: Successfully converted a digital token to a Circle token account. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: CreatePaymentTokenResponse + properties: + data: + $ref: '#/components/schemas/PaymentToken' + examples: + response: + value: + 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' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' /v1/businessAccount/banks/wires: post: security: @@ -1768,7 +1851,7 @@ paths: summary: Create a payment intent operationId: createPaymentIntent tags: - - Payment Intents + - Crypto Payment Intents requestBody: content: application/json: @@ -1820,7 +1903,7 @@ paths: summary: List all payment intents operationId: listPaymentIntents tags: - - Payment Intents + - Crypto Payment Intents parameters: - name: status description: Filters by the most recent `timeline.status` within the payment @@ -1870,8 +1953,7 @@ paths: response: value: data: - - idempotencyKey: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 amount: amount: '3.14' currency: USD @@ -1905,7 +1987,7 @@ paths: summary: Get a payment intent operationId: getPaymentIntent tags: - - Payment Intents + - Crypto Payment Intents parameters: - $ref: '#/components/parameters/IdPath' responses: @@ -1953,7 +2035,7 @@ paths: summary: Expire a payment intent operationId: expirePaymentIntent tags: - - Payment Intents + - Crypto Payment Intents parameters: - $ref: '#/components/parameters/IdPath' requestBody: @@ -2005,179 +2087,239 @@ paths: $ref: '#/components/responses/NotAuthorized' '404': $ref: '#/components/responses/NotFound' - /v1/payments: + /v1/addressBook/recipients: + post: + security: + - bearerAuth: [] + summary: Create a recipient + operationId: createAddressBookRecipient + tags: + - Crypto Address Book + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddressBookRecipientRequest' + responses: + '201': + description: Successfully created an address book recipient. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: CreateAddressBookRecipientResponse + properties: + data: + $ref: '#/components/schemas/AddressBookRecipient' + examples: + response: + value: + data: + id: 8755d0ea-14f9-4259-b092-de23c14b6568 + chain: ETH + address: '0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle + status: pending + createDate: '2022-07-21T20:13:35.578678Z' + updateDate: '2022-07-21T20:19:24.859052Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' get: security: - bearerAuth: [] + summary: List all recipients + operationId: listAddressBookRecipients + tags: + - Crypto Address Book parameters: - - $ref: '#/components/parameters/Source' - - $ref: '#/components/parameters/SettlementId' - - $ref: '#/components/parameters/PaymentIntentId' - - $ref: '#/components/parameters/PaymentSourceType' - - $ref: '#/components/parameters/PaymentStatus' + - name: address + description: Filters results to fetch only address book recipients with the + provided address. + in: query + required: false + schema: + type: string + - name: chain + description: Filters results to fetch only address book recipients with the + provided chain. + in: query + required: false + schema: + type: string + - name: email + description: Filters results to fetch only address book recipients that have + the provided email in their metadata. + in: query + required: false + schema: + type: string + - name: status + description: Filters results to fetch only address book recipients that have + the provided status. + in: query + required: false + schema: + type: string + enum: + - pending + - inactive + - active + - denied - $ref: '#/components/parameters/From' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/PageBefore' - $ref: '#/components/parameters/PageAfter' - $ref: '#/components/parameters/PageSize' - summary: List all payments - operationId: listPayments - tags: - - Payments responses: '200': - description: Successfully retrieved a list of payments. + description: Successfully retrieved a list of address book recipients. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListPaymentsResponse + title: ListAddressBookRecipientsResponse properties: data: type: array items: - oneOf: - - $ref: '#/components/schemas/FiatPayment' - - $ref: '#/components/schemas/CryptoPayment' - - $ref: '#/components/schemas/FiatCancel' - - $ref: '#/components/schemas/FiatRefund' - discriminator: - propertyName: type - mapping: - Fiat Payment: '#/components/schemas/FiatPayment' - Crypto Payment: '#/components/schemas/CryptoPayment' - Fiat Cancel: '#/components/schemas/FiatCancel' - Fiat Refund: '#/components/schemas/FiatRefund' + $ref: '#/components/schemas/AddressBookRecipient' examples: - Fiat Payment: + response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment + chain: ALGO + address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + addressTag: '123456789' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle status: pending - captured: false - captureAmount: - amount: '3.14' - currency: USD - captureDate: '2020-04-10T02:13:30.000Z' - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - description: Payment - status: pending - createDate: '2020-04-10T02:13:30.000Z' - refunds: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' - Crypto Payment: - value: - data: - - id: 66c56b6a-fc79-338b-8b94-aacc4f0f18de - type: payment - status: paid - amount: - amount: '1.00' - currency: USD - fees: - amount: '0.01' - currency: USD - 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' - createDate: '2022-07-21T20:16:35.092852Z' - updateDate: '2022-07-21T20:19:24.719313Z' - Fiat Cancel: + '401': + $ref: '#/components/responses/NotAuthorized' + /v1/addressBook/recipients/{id}: + get: + parameters: + - $ref: '#/components/parameters/IdPath' + security: + - bearerAuth: [] + summary: Get a recipient + operationId: getAddressBookRecipient + tags: + - Crypto Address Book + responses: + '200': + description: Successfully retrieved an address book recipient. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: GetAddressBookRecipientResponse + properties: + data: + $ref: '#/components/schemas/AddressBookRecipient' + examples: + response: value: data: - - id: 2dc266f5-0658-48ec-a81f-9c768279564d - type: cancel - status: confirmed - description: Cancel Payment - amount: - amount: '10.00' - currency: USD - createDate: '2022-04-21T21:50:34.274Z' - updateDate: '2022-04-21T21:50:34.647839Z' - merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b - merchantWalletId: '1000174786' - source: - id: bc9157fe-5d73-48fe-9e77-9f6723bdcfeb - type: card - originalPayment: - id: 2812f549-062a-4bdd-8ee5-b521aa48a84d - type: payment - status: failed - createDate: '2022-04-21T21:47:41.501Z' - updateDate: '2022-04-21T21:50:34.669012Z' - reason: requested_by_customer - Fiat Refund: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + chain: ALGO + address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + addressTag: '123456789' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle + status: pending + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + patch: + parameters: + - $ref: '#/components/parameters/IdPath' + security: + - bearerAuth: [] + summary: Modify a recipient + operationId: modifyAddressBookRecipient + tags: + - Crypto Address Book + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddressBookRecipientModifyRequest' + responses: + '200': + description: Successfully updated the address book recipient. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: ModifyAddressBookRecipientResponse + properties: + data: + $ref: '#/components/schemas/AddressBookRecipient' + examples: + response: value: data: - - id: 03fbe7da-096a-4763-af77-e43006cd83be - type: refund - status: paid - description: Refund Payment - amount: - amount: '3.14' - currency: USD - fees: - amount: '0.00' - currency: USD - createDate: '2022-04-21T12:49:21.146Z' - updateDate: '2022-04-21T12:54:10.596976Z' - merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b - merchantWalletId: '1000174786' - source: - id: 45fa5524-41b9-48ca-94cd-f45cb36cce4d - type: card - originalPayment: - id: 895f8db5-1d8c-407d-9533-b5ca3fbcc74e - type: payment - status: paid - createDate: '2022-04-06T19:33:29.690Z' - updateDate: '2022-04-06T19:47:23.681180Z' - reason: requested_by_customer + id: 8755d0ea-14f9-4259-b092-de23c14b6568 + chain: ETH + address: '0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle + status: pending + createDate: '2022-07-21T20:13:35.578678Z' + updateDate: '2022-07-21T20:19:24.859052Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + delete: + parameters: + - $ref: '#/components/parameters/IdPath' + security: + - bearerAuth: [] + summary: Delete a recipient + operationId: deleteAddressBookRecipient + tags: + - Crypto Address Book + responses: + '200': + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + description: Successfully removed the address book recipient. + '400': + $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + /v1/payments: post: security: - bearerAuth: [] @@ -2326,6 +2468,178 @@ paths: $ref: '#/components/responses/NotAuthorized' '404': $ref: '#/components/responses/NotFound' + get: + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/Source' + - $ref: '#/components/parameters/SettlementId' + - $ref: '#/components/parameters/PaymentIntentId' + - $ref: '#/components/parameters/PaymentSourceType' + - $ref: '#/components/parameters/PaymentStatus' + - $ref: '#/components/parameters/From' + - $ref: '#/components/parameters/To' + - $ref: '#/components/parameters/PageBefore' + - $ref: '#/components/parameters/PageAfter' + - $ref: '#/components/parameters/PageSize' + summary: List all payments + operationId: listPayments + tags: + - Payments + responses: + '200': + description: Successfully retrieved a list of payments. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: ListPaymentsResponse + properties: + data: + type: array + items: + oneOf: + - $ref: '#/components/schemas/FiatPayment' + - $ref: '#/components/schemas/CryptoPayment' + - $ref: '#/components/schemas/FiatCancel' + - $ref: '#/components/schemas/FiatRefund' + discriminator: + propertyName: type + mapping: + Fiat Payment: '#/components/schemas/FiatPayment' + Crypto Payment: '#/components/schemas/CryptoPayment' + Fiat Cancel: '#/components/schemas/FiatCancel' + Fiat Refund: '#/components/schemas/FiatRefund' + examples: + Fiat Payment: + value: + data: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: payment + merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 + merchantWalletId: '212000' + amount: + amount: '3.14' + currency: USD + source: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: card + description: Payment + status: pending + captured: false + captureAmount: + amount: '3.14' + currency: USD + captureDate: '2020-04-10T02:13:30.000Z' + requiredAction: + type: three_d_secure_required + redirectUrl: https://example.org + cancel: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: cancel + description: Payment + status: pending + createDate: '2020-04-10T02:13:30.000Z' + refunds: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: payment + amount: + amount: '3.14' + currency: USD + description: Payment + status: pending + requiredAction: + type: three_d_secure_required + redirectUrl: https://example.org + fees: + amount: '3.14' + currency: USD + createDate: '2020-04-10T02:13:30.000Z' + fees: + amount: '3.14' + currency: USD + channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + Crypto Payment: + value: + data: + - id: 66c56b6a-fc79-338b-8b94-aacc4f0f18de + type: payment + status: paid + amount: + amount: '1.00' + currency: USD + fees: + amount: '0.01' + currency: USD + 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' + createDate: '2022-07-21T20:16:35.092852Z' + updateDate: '2022-07-21T20:19:24.719313Z' + Fiat Cancel: + value: + data: + - id: 2dc266f5-0658-48ec-a81f-9c768279564d + type: cancel + status: confirmed + description: Cancel Payment + amount: + amount: '10.00' + currency: USD + createDate: '2022-04-21T21:50:34.274Z' + updateDate: '2022-04-21T21:50:34.647839Z' + merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b + merchantWalletId: '1000174786' + source: + id: bc9157fe-5d73-48fe-9e77-9f6723bdcfeb + type: card + originalPayment: + id: 2812f549-062a-4bdd-8ee5-b521aa48a84d + type: payment + status: failed + createDate: '2022-04-21T21:47:41.501Z' + updateDate: '2022-04-21T21:50:34.669012Z' + reason: requested_by_customer + Fiat Refund: + value: + data: + - id: 03fbe7da-096a-4763-af77-e43006cd83be + type: refund + status: paid + description: Refund Payment + amount: + amount: '3.14' + currency: USD + fees: + amount: '0.00' + currency: USD + createDate: '2022-04-21T12:49:21.146Z' + updateDate: '2022-04-21T12:54:10.596976Z' + merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b + merchantWalletId: '1000174786' + source: + id: 45fa5524-41b9-48ca-94cd-f45cb36cce4d + type: card + originalPayment: + id: 895f8db5-1d8c-407d-9533-b5ca3fbcc74e + type: payment + status: paid + createDate: '2022-04-06T19:33:29.690Z' + updateDate: '2022-04-06T19:47:23.681180Z' + reason: requested_by_customer + '401': + $ref: '#/components/responses/NotAuthorized' /v1/payments/{id}: get: parameters: @@ -2354,7 +2668,7 @@ paths: discriminator: propertyName: type mapping: - Fiat Payment: '#/components/schemas/FiatPayment' + Fiat Payment: '#/components/schemas/FiatPaymentPolymorphic' Crypto Payment: '#/components/schemas/CryptoPayment' examples: Fiat Payment: @@ -2847,21 +3161,94 @@ paths: fees: amount: '3.14' currency: USD - trackingRef: '24910599141085313498894' - errorCode: payment_failed - metadata: - email: satoshi@circle.com - phoneNumber: '+14155555555' + trackingRef: '24910599141085313498894' + errorCode: payment_failed + metadata: + email: satoshi@circle.com + phoneNumber: '+14155555555' + riskEvaluation: + decision: approved + reason: '3000' + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + /v1/businessAccount/payouts: + post: + security: + - bearerAuth: [] + summary: Create a payout + operationId: createBusinessPayout + tags: + - Payouts + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BusinessPayoutCreationRequest' + responses: + '201': + description: Successfully created a payout. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: CreateBusinessPayoutResponse + properties: + data: + $ref: '#/components/schemas/BusinessPayout' + examples: + response: + value: + data: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + sourceWalletId: '53535335' + destination: + type: wire + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + name: COMMERZBANK AG ****3000 + amount: + amount: '3.14' + currency: USD + fees: + amount: '3.14' + currency: USD + status: pending + trackingRef: CIR-6ESOQANEP3NAO + errorCode: insufficient_funds riskEvaluation: decision: approved reason: '3000' + adjustments: + fxCredit: + amount: '3.14' + currency: USD + fxDebit: + amount: '3.14' + currency: USD + return: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + payoutId: abdb500d-4a59-457c-801f-2d418c8703ac + amount: + amount: '3.14' + currency: USD + fees: + amount: '3.14' + currency: USD + reason: payout_returned + status: pending + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' - /v1/businessAccount/payouts: get: security: - bearerAuth: [] @@ -2885,6 +3272,7 @@ paths: required: false schema: type: array + uniqueItems: true items: $ref: '#/components/schemas/PayoutStatus' - $ref: '#/components/parameters/From' @@ -2957,28 +3345,26 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' '401': $ref: '#/components/responses/NotAuthorized' - post: + /v1/businessAccount/payouts/{id}: + get: + parameters: + - $ref: '#/components/parameters/IdPath' security: - bearerAuth: [] - summary: Create a payout - operationId: createBusinessPayout + summary: Get a payout + operationId: getBusinessPayout tags: - Payouts - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/BusinessPayoutCreationRequest' responses: - '201': - description: Successfully created a payout. + '200': + description: Successfully retrieved a payout. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: CreateBusinessPayoutResponse + title: GetBusinessPayoutResponse properties: data: $ref: '#/components/schemas/BusinessPayout' @@ -3026,38 +3412,54 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' - '400': - $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' - /v1/businessAccount/payouts/{id}: - get: - parameters: - - $ref: '#/components/parameters/IdPath' + '404': + $ref: '#/components/responses/NotFound' + /v1/payouts: + post: security: - bearerAuth: [] - summary: Get a payout - operationId: getBusinessPayout + summary: Create a payout + description: "\nCreate a wire, ACH, SEPA or crypto payout. \n\nThe following\ + \ table includes the supported pairs of amount.currency and toAmount.currency\ + \ for address book payouts:\n\n| amount.currency | toAmount.currency |\n\ + | ---------------- | ------------ |\n| USD | USD \ + \ |\n| USD | BTC |\n| USD |\ + \ ETH |\n| USD | MTC |\n| EUR \ + \ | EUR |\n| BTC | USD \ + \ |\n| BTC | BTC |\n| ETH | USD \ + \ |\n| ETH | ETH |\n" + operationId: createPayout tags: - Payouts + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/FiatPayoutCreationRequest' + - $ref: '#/components/schemas/CryptoPayoutCreationRequest' responses: - '200': - description: Successfully retrieved a payout. + '201': + description: Successfully created a payout. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: GetBusinessPayoutResponse + title: CreatePayoutResponse properties: data: - $ref: '#/components/schemas/BusinessPayout' + oneOf: + - $ref: '#/components/schemas/FiatPayout' + - $ref: '#/components/schemas/CryptoPayout' examples: - response: + Fiat Payout: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 sourceWalletId: '53535335' destination: type: wire @@ -3066,6 +3468,9 @@ paths: amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: EUR fees: amount: '3.14' currency: USD @@ -3097,19 +3502,51 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + Crypto Payout: + value: + data: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + sourceWalletId: '53535335' + destination: + type: address_book + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + amount: + amount: '3.14' + currency: USD + toAmount: + amount: '3.14' + currency: ETH + fees: + amount: '3.14' + currency: USD + status: pending + errorCode: transaction_denied + riskEvaluation: + decision: denied + reason: '4000' + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' - /v1/payouts: get: security: - bearerAuth: [] parameters: - name: source - description: Universally unique identifier (UUID v4) for the source wallet. - Filters the results to fetch all payouts made from a source wallet. If not - provided, payouts from all wallets will be returned. + description: Identifier for the source wallet. Filters the fetched payout + results to only be from a specific source wallet. If not provided, payouts + from all wallets will be returned. + in: query + required: false + schema: + type: string + example: '1000565227' + - name: destination + description: Universally unique identifier (UUID v4) for the destination. + Filters the fetched payout results made to a specific destination. If not + provided, payouts to all destinations will be returned. in: query required: false schema: @@ -3117,14 +3554,15 @@ paths: format: uuid example: 54c1cbab-c419-450f-ad23-906fa03af7f0 - name: type - description: Destination bank account type. Filters the results to fetch all - payouts made to a specified destination bank account type. This query parameter - can be passed multiple times to fetch results matching multiple destination - bank account types. + description: Destination type. Filters the results to fetch all payouts made + to a specified destination type. This query parameter can be passed multiple + times to fetch results matching multiple destination types. The address_book + destination type cannot be combined with other types. in: query required: false schema: type: array + uniqueItems: true items: $ref: '#/components/schemas/PayoutDestinationType' - name: status @@ -3134,9 +3572,40 @@ paths: required: false schema: type: array + uniqueItems: true items: $ref: '#/components/schemas/PayoutStatus' - - $ref: '#/components/parameters/Destination' + - name: sourceCurrency + description: Queries items with the specified source currency `amount.currency`. + Matches any source currency if unspecified. + in: query + required: false + schema: + type: string + enum: + - USD + - EUR + - BTC + - ETH + - MTC + - FLW + - MAN + - name: destinationCurrency + description: Queries items with the specified destination currency `toAmount.currency`. + Matches any destination currency if unspecified. + in: query + required: false + schema: + type: string + enum: + - USD + - EUR + - BTC + - ETH + - MTC + - FLW + - MAN + - $ref: '#/components/parameters/Chain' - $ref: '#/components/parameters/From' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/PageBefore' @@ -3160,12 +3629,14 @@ paths: data: type: array items: - $ref: '#/components/schemas/Payout' + anyOf: + - $ref: '#/components/schemas/FiatPayout' + - $ref: '#/components/schemas/CryptoPayout' examples: - response: + Fiat Payout: value: data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + id: b8627ae8-732b-4d25-b947-1df8f4007a29 sourceWalletId: '53535335' destination: type: wire @@ -3174,6 +3645,9 @@ paths: amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: EUR fees: amount: '3.14' currency: USD @@ -3205,79 +3679,30 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' - '401': - $ref: '#/components/responses/NotAuthorized' - post: - security: - - bearerAuth: [] - summary: Create a payout - operationId: createPayout - tags: - - Payouts - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PayoutCreationRequest' - responses: - '201': - description: Successfully created a payout. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: CreatePayoutResponse - properties: - data: - $ref: '#/components/schemas/Payout' - examples: - response: + Crypto Payout: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 sourceWalletId: '53535335' destination: - type: wire + type: address_book id: b8627ae8-732b-4d25-b947-1df8f4007a29 - name: COMMERZBANK AG ****3000 amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: ETH fees: amount: '3.14' currency: USD status: pending - trackingRef: CIR-6ESOQANEP3NAO - errorCode: insufficient_funds + errorCode: transaction_denied riskEvaluation: - decision: approved - reason: '3000' - adjustments: - fxCredit: - amount: '3.14' - currency: USD - fxDebit: - amount: '3.14' - currency: USD - return: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - payoutId: abdb500d-4a59-457c-801f-2d418c8703ac - amount: - amount: '3.14' - currency: USD - fees: - amount: '3.14' - currency: USD - reason: payout_returned - status: pending - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' + decision: denied + reason: '4000' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' - '400': - $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' /v1/payouts/{id}: @@ -3302,9 +3727,11 @@ paths: title: GetPayoutResponse properties: data: - $ref: '#/components/schemas/DetailedPayout' + oneOf: + - $ref: '#/components/schemas/FiatDetailedPayout' + - $ref: '#/components/schemas/CryptoPayout' examples: - response: + Fiat Payout: value: data: id: b8627ae8-732b-4d25-b947-1df8f4007a29 @@ -3316,6 +3743,9 @@ paths: amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: EUR fees: amount: '3.14' currency: USD @@ -3348,6 +3778,30 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + Crypto Payout: + value: + data: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + sourceWalletId: '53535335' + destination: + type: address_book + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + amount: + amount: '3.14' + currency: USD + toAmount: + amount: '3.14' + currency: ETH + fees: + amount: '3.14' + currency: USD + status: pending + errorCode: transaction_denied + riskEvaluation: + decision: denied + reason: '4000' + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' '401': $ref: '#/components/responses/NotAuthorized' '404': @@ -3371,35 +3825,82 @@ paths: - Returns responses: '200': - description: Successfully retrieved a list of payout returns. + description: Successfully retrieved a list of payout returns. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: ListReturnsResponse + properties: + data: + type: array + items: + $ref: '#/components/schemas/UnwithdrawalObject' + examples: + response: + value: + data: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + payoutId: abdb500d-4a59-457c-801f-2d418c8703ac + amount: + amount: '3.14' + currency: USD + fees: + amount: '3.14' + currency: USD + reason: payout_returned + status: pending + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' + /v1/exchange/rates/{trading-pair}: + get: + security: + - bearerAuth: [] + summary: Get a exchange rate + description: Fetch the current rates for the specified trading pair. The trading + pair is defined by a base currency followed by a quote currency. The response + contains buy and sell rates denominated in the quote currency. **Exchange + rate is an estimate only and is subject to change by the time you submit the + actual request.** + operationId: getExchangeRates + tags: + - Crypto Exchange Rates + parameters: + - name: trading-pair + in: path + required: true + schema: + type: string + enum: + - BTC-USD + - ETH-USD + - FLOW-USD + responses: + '200': + description: Successfully retrieved rates. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListReturnsResponse + title: GetExchangeRatesResponse properties: data: - type: array - items: - $ref: '#/components/schemas/UnwithdrawalObject' + $ref: '#/components/schemas/Rate' examples: response: value: data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - payoutId: abdb500d-4a59-457c-801f-2d418c8703ac - amount: - amount: '3.14' - currency: USD - fees: - amount: '3.14' - currency: USD - reason: payout_returned - status: pending + buy: '46317.59000' + sell: '45400.41000' createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' '400': $ref: '#/components/responses/BadRequest' '401': @@ -3546,6 +4047,7 @@ paths: paymentId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 reasonCode: '10.4' + status: active category: Canceled Recurring Payment history: - type: 1st Chargeback @@ -3594,6 +4096,7 @@ paths: paymentId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 reasonCode: '10.4' + status: active category: Canceled Recurring Payment history: - type: 1st Chargeback @@ -4456,7 +4959,7 @@ paths: content: application/json: schema: - title: CreateAchAccountResponse + title: CreateMockAchAccountResponse properties: data: $ref: '#/components/schemas/MockAchAccountResponse' @@ -4903,6 +5406,15 @@ components: description: The country code of the issuer bank. Follows the ISO 3166-1 alpha-2 standard. example: US + fundingType: + description: The funding type of the card. Possible values are `credit`, + `debit`, `prepaid`, and `unknown`. + type: string + enum: + - credit + - debit + - prepaid + - unknown fingerprint: $ref: '#/components/schemas/Fingerprint' verification: @@ -5184,6 +5696,203 @@ components: $ref: '#/components/schemas/CardExpMonth' expYear: $ref: '#/components/schemas/CardExpYear' + ApplePayTokenEcHeader: + type: object + required: + - ephemeralPublicKey + - publicKeyHash + - transactionId + properties: + applicationData: + description: Optional. Hash of the applicationData property of the original + PKPaymentRequest object. If the value of that property is null, this key + is omitted. + type: string + example: '' + ephemeralPublicKey: + description: Ephemeral public key bytes. + type: string + example: MFkwEwYHKoZIzj.../zlsw== + publicKeyHash: + description: "Hash of the X.509 encoded public key bytes of the merchant\u2019\ + s certificate." + type: string + example: tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0= + transactionId: + description: Transaction identifier, generated on the device. + type: string + example: 3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4 + ApplePayTokenRsaHeader: + type: object + required: + - wrappedKey + - publicKeyHash + - transactionId + properties: + applicationData: + description: Optional. Hash of the applicationData property of the original + PKPaymentRequest object. If the value of that property is null, this key + is omitted. + type: string + wrappedKey: + description: The symmetric key wrapped using your RSA public key. + type: string + publicKeyHash: + description: "Hash of the X.509 encoded public key bytes of the merchant\u2019\ + s certificate." + type: string + transactionId: + description: Transaction identifier, generated on the device. + type: string + ApplePayToken: + type: object + required: + - version + - data + - signature + - header + properties: + version: + description: ApplePay token version information. + type: string + enum: + - EC_v1 + - RSA_v1 + data: + description: Encrypted payment data. Base64 encoded as a string. + type: string + example: t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+...T6Ms7PhiNZpuGEE2QE= + signature: + description: Signature of the payment and header data. The signature includes + the signing certificate, its intermediate CA certificate, and information + about the signing algorithm. + type: string + example: MIAGCSqGSIb3DQEHAqCAMIACAQEx.../WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA= + header: + description: Additional version-dependent information used to decrypt and + verify the payment. + oneOf: + - $ref: '#/components/schemas/ApplePayTokenEcHeader' + - $ref: '#/components/schemas/ApplePayTokenRsaHeader' + GooglePayToken: + type: object + required: + - signature + - protocolVersion + - signedMessage + properties: + signature: + description: Verifies the message came from Google. The signature is created + using ECDSA. + type: string + protocolVersion: + description: Identifies which encryption/signing scheme created this message. + In this way, the protocol can evolve over time if needed. If it is not + set, assume ECv0. + type: string + signedMessage: + description: A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, + and tag. To simplify the signature verification process, this value is + serialized. + type: string + PaymentTokenRequest: + type: object + required: + - idempotencyKey + - type + - tokenData + properties: + idempotencyKey: + $ref: '#/components/schemas/IdempotencyKey' + type: + description: Type of the digital wallet token. + type: string + enum: + - applepay + - googlepay + tokenData: + description: The token data + oneOf: + - $ref: '#/components/schemas/ApplePayToken' + - $ref: '#/components/schemas/GooglePayToken' + TokenizedCardDetails: + type: object + required: + - expMonth + - expYear + - last4 + - bin + properties: + expMonth: + description: The card's expiration month. + type: integer + example: 1 + expYear: + description: Four digit number representing the card's expiration year. + type: integer + example: 2020 + network: + description: The network of the card. + type: string + enum: + - VISA + - MASTERCARD + - AMEX + - UNKNOWN + last4: + description: The last 4 digits of the card. + type: string + example: '0123' + bin: + description: The bank identification number (BIN), the first 6 digits of + the card. + type: string + example: '401230' + fundingType: + description: The funding type of the card. + type: string + enum: + - credit + - debit + - prepaid + - unknown + issuerCountry: + description: The country code of the issuer bank. Follows the ISO 3166-1 + alpha-2 standard. + type: string + example: US + PaymentToken: + type: object + required: + - id + - type + - expiresOn + - cardDetails + - createDate + - updateDate + properties: + id: + description: Unique system generated identifier for the digital wallet token. + type: string + format: uuid + example: gc988ed5-c189-4f70-a074-e5beb7eb8e32 + type: + description: Type of the digital wallet token. + type: string + enum: + - applepay + - googlepay + expiresOn: + description: Datetime when the digital token expires. ISO-8601. + type: string + format: date-time + example: '2022-01-18T19:20:00Z' + cardDetails: + $ref: '#/components/schemas/TokenizedCardDetails' + createDate: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' BankAddress: type: object description: The address details for the bank, as provided during bank account @@ -6059,11 +6768,9 @@ components: $ref: '#/components/schemas/Chain' address: type: string - readOnly: true example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' PaymentIntentFees: type: object - readOnly: true required: - type - amount @@ -6085,7 +6792,6 @@ components: - USD Timeline: type: object - readOnly: true required: - status - time @@ -6108,11 +6814,6 @@ components: description: ISO-8601 UTC date/time format. type: string format: date-time - UtcTimestampReadOnly: - type: string - readOnly: true - description: ISO-8601 UTC date/time format. - example: '2020-04-10T02:13:30.000Z' PaymentIntent: type: object required: @@ -6121,11 +6822,8 @@ components: - settlementCurrency - paymentMethods properties: - idempotencyKey: - $ref: '#/components/schemas/IdempotencyKey' id: type: string - readOnly: true description: Unique system generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 @@ -6134,7 +6832,6 @@ components: amountPaid: description: Sum of the the amount paid. type: object - readOnly: true required: - amount - currency @@ -6162,13 +6859,11 @@ components: $ref: '#/components/schemas/PaymentMethodBlockchain' fees: type: array - readOnly: true items: $ref: '#/components/schemas/PaymentIntentFees' paymentIds: description: List of associated payments. type: array - readOnly: true items: type: string format: uuid @@ -6176,15 +6871,79 @@ components: timeline: description: State management timeline. type: array - readOnly: true items: $ref: '#/components/schemas/Timeline' expiresOn: - $ref: '#/components/schemas/UtcTimestampReadOnly' + $ref: '#/components/schemas/UtcTimestamp' updateDate: - $ref: '#/components/schemas/UtcTimestampReadOnly' + $ref: '#/components/schemas/UtcTimestamp' + createDate: + $ref: '#/components/schemas/UtcTimestamp' + AddressBookRecipientMetadata: + type: object + properties: + nickname: + type: string + description: Nickname related to the address. + example: sample nickname + email: + $ref: '#/components/schemas/Email' + bns: + type: string + description: Blockchain Name Service (e.g. ENS) domain for the address. + example: sample.circle + AddressBookRecipient: + type: object + required: + - chain + - address + - metadata + properties: + id: + $ref: '#/components/schemas/Id' + chain: + $ref: '#/components/schemas/Chain' + address: + $ref: '#/components/schemas/Address' + addressTag: + $ref: '#/components/schemas/AddressTag' + metadata: + $ref: '#/components/schemas/AddressBookRecipientMetadata' + status: + type: string + description: Status of the address book recipient. + enum: + - pending + - inactive + - active + - denied createDate: - $ref: '#/components/schemas/UtcTimestampReadOnly' + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' + AddressBookRecipientRequest: + type: object + required: + - idempotencyKey + - chain + - address + - metadata + properties: + idempotencyKey: + $ref: '#/components/schemas/IdempotencyKey' + chain: + $ref: '#/components/schemas/Chain' + address: + $ref: '#/components/schemas/Address' + addressTag: + $ref: '#/components/schemas/AddressTag' + metadata: + $ref: '#/components/schemas/AddressBookRecipientMetadata' + AddressBookRecipientModifyRequest: + type: object + properties: + metadata: + $ref: '#/components/schemas/AddressBookRecipientMetadata' IdMerchant: type: string description: Unique system generated identifier for the merchant. @@ -6989,13 +7748,14 @@ components: - pending - complete - failed - PayoutDestinationType: + BusinessAccountPayoutDestinationType: type: string description: The destination bank account type. enum: - wire - ach - sepa + - signet BankDestination: type: object description: The destination bank account. @@ -7004,14 +7764,13 @@ components: - id properties: type: - $ref: '#/components/schemas/PayoutDestinationType' + $ref: '#/components/schemas/BusinessAccountPayoutDestinationType' id: $ref: '#/components/schemas/Id' name: type: string description: Bank name plus last four digits of the bank account number or IBAN. - readOnly: true example: COMMERZBANK AG ****3000 PayoutErrorCode: type: string @@ -7123,6 +7882,7 @@ components: enum: - wire - sen + - signet id: $ref: '#/components/schemas/Id' BusinessPayoutCreationRequest: @@ -7138,7 +7898,110 @@ components: $ref: '#/components/schemas/BusinessDestinationRequest' amount: $ref: '#/components/schemas/FiatMoney' - Payout: + PayoutDestinationType: + type: string + description: The destination type. + enum: + - wire + - ach + - sepa + - address_book + FiatPayoutDestinationType: + type: string + description: The destination type. + enum: + - wire + - ach + - sepa + FiatPayoutDestination: + type: object + description: The destination. + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/FiatPayoutDestinationType' + id: + $ref: '#/components/schemas/Id' + name: + type: string + description: Bank name plus last four digits of the bank account number + or IBAN. + example: COMMERZBANK AG ****3000 + PayoutMoney: + type: object + required: + - amount + - currency + properties: + amount: + type: string + description: Magnitude of the amount, in units of the currency, with a `.`. + example: '3.14' + currency: + type: string + description: Currency code for the amount. + enum: + - USD + - EUR + - BTC + - ETH + - MTC + - FLW + - MAN + FiatPayout: + type: object + properties: + id: + $ref: '#/components/schemas/Id' + sourceWalletId: + type: string + description: The identifier of the source wallet used to fund a payout. + example: '53535335' + destination: + $ref: '#/components/schemas/FiatPayoutDestination' + amount: + $ref: '#/components/schemas/FiatMoneyUsd' + toAmount: + $ref: '#/components/schemas/PayoutMoney' + fees: + $ref: '#/components/schemas/FiatMoneyUsd' + status: + $ref: '#/components/schemas/PayoutStatus' + trackingRef: + description: A payout tracking reference. Will be present once known. + nullable: true + example: CIR-6ESOQANEP3NAO + errorCode: + $ref: '#/components/schemas/PayoutErrorCode' + riskEvaluation: + $ref: '#/components/schemas/RiskEvaluation' + adjustments: + $ref: '#/components/schemas/FinalAdjustments' + return: + $ref: '#/components/schemas/UnwithdrawalObject' + createDate: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' + CryptoPayoutDestinationType: + type: string + description: The destination type. + enum: + - address_book + CryptoPayoutDestination: + type: object + description: The destination. + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/CryptoPayoutDestinationType' + id: + $ref: '#/components/schemas/Id' + CryptoPayout: type: object properties: id: @@ -7148,25 +8011,19 @@ components: description: The identifier of the source wallet used to fund a payout. example: '53535335' destination: - $ref: '#/components/schemas/BankDestination' + $ref: '#/components/schemas/CryptoPayoutDestination' amount: - $ref: '#/components/schemas/FiatMoneyUsd' + $ref: '#/components/schemas/PayoutMoney' + toAmount: + $ref: '#/components/schemas/PayoutMoney' fees: - $ref: '#/components/schemas/FiatMoneyUsd' + $ref: '#/components/schemas/PayoutMoney' status: $ref: '#/components/schemas/PayoutStatus' - trackingRef: - description: A payout tracking reference. Will be present once known. - nullable: true - example: CIR-6ESOQANEP3NAO errorCode: $ref: '#/components/schemas/PayoutErrorCode' riskEvaluation: $ref: '#/components/schemas/RiskEvaluation' - adjustments: - $ref: '#/components/schemas/FinalAdjustments' - return: - $ref: '#/components/schemas/UnwithdrawalObject' createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: @@ -7179,7 +8036,7 @@ components: properties: beneficiaryEmail: $ref: '#/components/schemas/Email' - PayoutCreationRequest: + FiatPayoutCreationRequest: type: object required: - idempotencyKey @@ -7192,12 +8049,147 @@ components: source: $ref: '#/components/schemas/WalletLocation' destination: - $ref: '#/components/schemas/BankDestination' + type: object + description: The destination. + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/FiatPayoutDestinationType' + id: + $ref: '#/components/schemas/Id' amount: $ref: '#/components/schemas/FiatMoneyUsd' metadata: $ref: '#/components/schemas/MetadataPayout' - DetailedPayout: + IdentityAddress: + type: object + required: + - line1 + - city + - district + - postalCode + - country + properties: + line1: + type: string + description: Line one of the street address. + maxLength: 1024 + example: 100 Money Street + line2: + type: string + description: Line two of the street address. + maxLength: 1024 + example: Suite 1 + city: + type: string + description: City portion of the address. + maxLength: 1024 + example: Boston + district: + description: State / County / Province / Region portion of the address. + If the country is US or Canada, then district is required and should use + the two-letter code for the subdivision. + type: string + maxLength: 16 + example: MA + postalCode: + type: string + description: Postal / ZIP code of the address. + maxLength: 16 + example: '01234' + country: + type: string + description: Country portion of the address. Formatted as a two-letter country + code specified in ISO 3166-1 alpha-2. + maxLength: 2 + example: US + Identity: + type: object + description: "The identity of the originator. Identities are required when:\n\ + \ * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n\ + \ * `amount.amount` >= $3,000 in value\n" + required: + - type + - name + - addresses + properties: + type: + type: string + description: 'The type of identity for the originator. + + * `individual` - A uniquely distinguishable individual. + + * `business` - Any entity other than a natural person that can establish + a permanent customer relationship with an affected entity or otherwise + own property. This can include companies, foundations, anstalt, partnerships, + associations and other relevantly similar entities. + + ' + enum: + - individual + - business + name: + type: string + description: Full name of the identity. + example: Satoshi Nakamoto + maxLength: 1024 + addresses: + type: array + items: + $ref: '#/components/schemas/IdentityAddress' + TransferSourceWalletLocation: + description: A source wallet location. + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - wallet + id: + type: string + description: The id of the wallet. + example: '12345' + identities: + type: array + items: + $ref: '#/components/schemas/Identity' + ToAmount: + type: object + required: + - currency + properties: + currency: + type: string + description: Currency code for the amount. + enum: + - USD + - EUR + - BTC + - ETH + - MTC + CryptoPayoutCreationRequest: + type: object + required: + - idempotencyKey + - destination + - amount + properties: + idempotencyKey: + $ref: '#/components/schemas/IdempotencyKey' + source: + $ref: '#/components/schemas/TransferSourceWalletLocation' + destination: + $ref: '#/components/schemas/CryptoPayoutDestination' + amount: + $ref: '#/components/schemas/Money' + toAmount: + $ref: '#/components/schemas/ToAmount' + FiatDetailedPayout: type: object properties: id: @@ -7207,9 +8199,11 @@ components: type: string example: '53535335' destination: - $ref: '#/components/schemas/BankDestination' + $ref: '#/components/schemas/FiatPayoutDestination' amount: $ref: '#/components/schemas/FiatMoneyUsd' + toAmount: + $ref: '#/components/schemas/PayoutMoney' fees: $ref: '#/components/schemas/FiatMoneyUsd' status: @@ -7239,6 +8233,25 @@ components: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' + Rate: + type: object + required: + - buy + - sell + - createDate + properties: + buy: + type: string + description: The buy rate denominated in the quote currency of the trading + pair. + example: '46317.59000' + sell: + type: string + description: The sell rate denominated in the quote currency of the trading + pair. + example: '45400.41000' + createDate: + $ref: '#/components/schemas/UtcTimestamp' Settlement: type: object properties: @@ -7270,6 +8283,27 @@ components: to the chargeback item. format: uuid example: fc988ed5-c129-4f70-a064-e5beb7eb8e32 + ChargebackStatus: + type: string + enum: + - active + - resolved + - pending + - won + - lost + - canceled + - closed + description: "Enumerated status of the chargeback. `active` means you\u2019\ + ve received a dispute and you need to submit evidence if you want to defend\ + \ against it. 'resolved' means the disputed payment had been refunded previously.\ + \ Your account has not been debited. `pending` means we have acknowledged\ + \ your evidence and forwarded it to the card issuer. `won` means you have\ + \ won the dispute and your account has been credited. `lost` means the issuing\ + \ bank has rejected your evidence and you have lost the dispute. There are\ + \ no further financial implications. `canceled` means the issuing bank has\ + \ canceled the dispute and your account has been credited. `closed` means\ + \ the time to respond to this dispute has run out. No evidence can be submitted\ + \ at this point." ChargebackCategories: type: string description: Enumerated category of the chargeback status codes based on the @@ -7333,6 +8367,7 @@ components: - id - paymentId - merchantId + - status - history - reasonCode properties: @@ -7346,6 +8381,8 @@ components: description: Reason code given by the card network for the chargeback item. type: string example: '10.4' + status: + $ref: '#/components/schemas/ChargebackStatus' category: $ref: '#/components/schemas/ChargebackCategories' history: @@ -7444,101 +8481,6 @@ components: $ref: '#/components/schemas/Currency' chain: $ref: '#/components/schemas/Chain' - IdentityAddress: - type: object - required: - - line1 - - city - - district - - postalCode - - country - properties: - line1: - type: string - description: Line one of the street address. - maxLength: 1024 - example: 100 Money Street - line2: - type: string - description: Line two of the street address. - maxLength: 1024 - example: Suite 1 - city: - type: string - description: City portion of the address. - maxLength: 1024 - example: Boston - district: - description: State / County / Province / Region portion of the address. - If the country is US or Canada, then district is required and should use - the two-letter code for the subdivision. - type: string - maxLength: 16 - example: MA - postalCode: - type: string - description: Postal / ZIP code of the address. - maxLength: 16 - example: '01234' - country: - type: string - description: Country portion of the address. Formatted as a two-letter country - code specified in ISO 3166-1 alpha-2. - maxLength: 2 - example: US - Identity: - type: object - description: "The identity of the originator. Identities are required when:\n\ - \ * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n\ - \ * `amount.amount` >= $3,000 in value\n" - required: - - type - - name - - addresses - properties: - type: - type: string - description: 'The type of identity for the originator. - - * `individual` - A uniquely distinguishable individual. - - * `business` - Any entity other than a natural person that can establish - a permanent customer relationship with an affected entity or otherwise - own property. This can include companies, foundations, anstalt, partnerships, - associations and other relevantly similar entities. - - ' - enum: - - individual - - business - name: - type: string - description: Full name of the identity. - example: Satoshi Nakamoto - maxLength: 1024 - addresses: - type: array - items: - $ref: '#/components/schemas/IdentityAddress' - TransferSourceWalletLocation: - description: A source wallet location. - type: object - required: - - type - - id - properties: - type: - type: string - enum: - - wallet - id: - type: string - description: The id of the wallet. - example: '12345' - identities: - type: array - items: - $ref: '#/components/schemas/Identity' TransferSourceBlockchainLocation: description: A source blockchain address. type: object @@ -7665,7 +8607,6 @@ components: fees: description: An array of fees applied to a transaction. This is only available when there is at least one non-zero fee. - readOnly: true type: array items: $ref: '#/components/schemas/Fee' @@ -7793,7 +8734,6 @@ components: fees: description: An array of fees applied to a transaction. This is only available when there is at least one non-zero fee. - readOnly: true type: array items: $ref: '#/components/schemas/Fee' @@ -8305,6 +9245,7 @@ components: required: false schema: type: array + uniqueItems: true items: type: string enum: @@ -8337,6 +9278,24 @@ components: type: string format: uuid example: e3d0a838-d732-49d0-bf44-73a668e38973 + Chain: + name: chain + description: Queries items with the specified chain. Matches any chain if unspecified + in: query + required: false + schema: + type: string + enum: + - ALGO + - AVAX + - BTC + - ETH + - FLOW + - HBAR + - MATIC + - SOL + - TRX + - XLM PaymentId: name: paymentId description: The payment ID associated with the chargeback. diff --git a/openapi/yaml/crypto-payments.yaml b/openapi/yaml/crypto-payments.yaml deleted file mode 100644 index 14216cb..0000000 --- a/openapi/yaml/crypto-payments.yaml +++ /dev/null @@ -1,1651 +0,0 @@ -openapi: 3.0.2 -servers: -- url: api-sandbox.circle.com -info: - version: 1.0.3 - title: Crypto Payments API - description: Crypto Payments collection Circle APIs. -tags: -- name: Payment Intents -- name: Payments -paths: - /v1/paymentIntents: - post: - security: - - bearerAuth: [] - summary: Create a payment intent - operationId: createPaymentIntent - tags: - - Payment Intents - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentIntent' - responses: - '201': - description: Successfully created a payment intent. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: CreatePaymentIntentResponse - properties: - data: - $ref: '#/components/schemas/PaymentIntent' - examples: - response: - value: - data: - id: 8755d0ea-14f9-4259-b092-de23c14b6568 - amount: - amount: '3.14' - 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' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' - get: - security: - - bearerAuth: [] - summary: List all payment intents - operationId: listPaymentIntents - tags: - - Payment Intents - parameters: - - name: status - description: Filters by the most recent `timeline.status` within the payment - intent. - in: query - required: false - schema: - type: string - enum: - - created - - pending - - complete - - expired - - failed - - name: context - description: Filters by the most recent `timeline.context` within the payment - intent. - in: query - required: false - schema: - type: string - enum: - - underpaid - - paid - - overpaid - - $ref: '#/components/parameters/From' - - $ref: '#/components/parameters/To' - - $ref: '#/components/parameters/PageBefore' - - $ref: '#/components/parameters/PageAfter' - - $ref: '#/components/parameters/PageSize' - responses: - '200': - description: Successfully retrieved a list of payment intents. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: ListPaymentIntentsResponse - properties: - data: - type: array - items: - $ref: '#/components/schemas/PaymentIntent' - examples: - response: - value: - data: - - idempotencyKey: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - amount: - amount: '3.14' - currency: USD - amountPaid: - amount: '3.14' - currency: USD - settlementCurrency: USD - paymentMethods: - - type: blockchain - chain: ALGO - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - fees: - - type: blockchainLeaseFee - amount: '3.14' - currency: USD - paymentIds: - - 69808f36-3e5e-4f37-bf82-ca79e4d70fc1 - timeline: - - status: created - context: underpaid - time: '2020-04-10T02:13:30.000Z' - expiresOn: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - createDate: '2020-04-10T02:13:30.000Z' - '401': - $ref: '#/components/responses/NotAuthorized' - /v1/paymentIntents/{id}: - get: - security: - - bearerAuth: [] - summary: Get a payment intent - operationId: getPaymentIntent - tags: - - Payment Intents - parameters: - - $ref: '#/components/parameters/IdPath' - responses: - '200': - description: Successfully retrieved a payment intent. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: GetPaymentIntentResponse - properties: - data: - $ref: '#/components/schemas/PaymentIntent' - examples: - response: - value: - data: - id: 8755d0ea-14f9-4259-b092-de23c14b6568 - amount: - amount: '3.14' - 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' - '401': - $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' - /v1/paymentIntents/{id}/expire: - post: - security: - - bearerAuth: [] - summary: Expire a payment intent - operationId: expirePaymentIntent - tags: - - Payment Intents - parameters: - - $ref: '#/components/parameters/IdPath' - requestBody: - content: - application/json: - schema: - type: object - responses: - '201': - description: Successfully expired a payment intent. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: ExpirePaymentIntentResponse - properties: - data: - $ref: '#/components/schemas/PaymentIntent' - examples: - response: - value: - data: - id: 8755d0ea-14f9-4259-b092-de23c14b6568 - amount: - amount: '3.14' - currency: USD - amountPaid: - amount: '3.14' - currency: USD - settlementCurrency: USD - paymentMethods: - - type: blockchain - chain: ETH - paymentIds: [] - timeline: - - status: expired - context: underpaid - reason: requested_by_merchant - time: '2022-07-21T21:45:54.569Z' - - status: created - time: '2022-07-21T20:13:35.579331Z' - createDate: '2022-07-21T20:13:35.578678Z' - updateDate: '2022-07-21T20:19:24.859052Z' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' - /v1/payments: - get: - security: - - bearerAuth: [] - parameters: - - $ref: '#/components/parameters/Source' - - $ref: '#/components/parameters/SettlementId' - - $ref: '#/components/parameters/PaymentIntentId' - - $ref: '#/components/parameters/PaymentSourceType' - - $ref: '#/components/parameters/PaymentStatus' - - $ref: '#/components/parameters/From' - - $ref: '#/components/parameters/To' - - $ref: '#/components/parameters/PageBefore' - - $ref: '#/components/parameters/PageAfter' - - $ref: '#/components/parameters/PageSize' - summary: List all payments - operationId: listPayments - tags: - - Payments - responses: - '200': - description: Successfully retrieved a list of payments. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: ListPaymentsResponse - properties: - data: - type: array - items: - oneOf: - - $ref: '#/components/schemas/FiatPayment' - - $ref: '#/components/schemas/CryptoPayment' - - $ref: '#/components/schemas/FiatCancel' - - $ref: '#/components/schemas/FiatRefund' - discriminator: - propertyName: type - mapping: - Fiat Payment: '#/components/schemas/FiatPayment' - Crypto Payment: '#/components/schemas/CryptoPayment' - Fiat Cancel: '#/components/schemas/FiatCancel' - Fiat Refund: '#/components/schemas/FiatRefund' - examples: - Fiat Payment: - value: - data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - captured: false - captureAmount: - amount: '3.14' - currency: USD - captureDate: '2020-04-10T02:13:30.000Z' - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - description: Payment - status: pending - createDate: '2020-04-10T02:13:30.000Z' - refunds: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - Crypto Payment: - value: - data: - - id: 66c56b6a-fc79-338b-8b94-aacc4f0f18de - type: payment - status: paid - amount: - amount: '1.00' - currency: USD - fees: - amount: '0.01' - currency: USD - 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' - createDate: '2022-07-21T20:16:35.092852Z' - updateDate: '2022-07-21T20:19:24.719313Z' - Fiat Cancel: - value: - data: - - id: 2dc266f5-0658-48ec-a81f-9c768279564d - type: cancel - status: confirmed - description: Cancel Payment - amount: - amount: '10.00' - currency: USD - createDate: '2022-04-21T21:50:34.274Z' - updateDate: '2022-04-21T21:50:34.647839Z' - merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b - merchantWalletId: '1000174786' - source: - id: bc9157fe-5d73-48fe-9e77-9f6723bdcfeb - type: card - originalPayment: - id: 2812f549-062a-4bdd-8ee5-b521aa48a84d - type: payment - status: failed - createDate: '2022-04-21T21:47:41.501Z' - updateDate: '2022-04-21T21:50:34.669012Z' - reason: requested_by_customer - Fiat Refund: - value: - data: - - id: 03fbe7da-096a-4763-af77-e43006cd83be - type: refund - status: paid - description: Refund Payment - amount: - amount: '3.14' - currency: USD - fees: - amount: '0.00' - currency: USD - createDate: '2022-04-21T12:49:21.146Z' - updateDate: '2022-04-21T12:54:10.596976Z' - merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b - merchantWalletId: '1000174786' - source: - id: 45fa5524-41b9-48ca-94cd-f45cb36cce4d - type: card - originalPayment: - id: 895f8db5-1d8c-407d-9533-b5ca3fbcc74e - type: payment - status: paid - createDate: '2022-04-06T19:33:29.690Z' - updateDate: '2022-04-06T19:47:23.681180Z' - reason: requested_by_customer - '401': - $ref: '#/components/responses/NotAuthorized' - /v1/payments/{id}: - get: - parameters: - - $ref: '#/components/parameters/IdPath' - security: - - bearerAuth: [] - summary: Get a payment - operationId: getPayment - tags: - - Payments - responses: - '200': - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - description: Successfully retrieved a payment. - content: - application/json: - schema: - title: GetPaymentResponse - properties: - data: - oneOf: - - $ref: '#/components/schemas/FiatPaymentPolymorphic' - - $ref: '#/components/schemas/CryptoPayment' - discriminator: - propertyName: type - mapping: - Fiat Payment: '#/components/schemas/FiatPayment' - Crypto Payment: '#/components/schemas/CryptoPayment' - examples: - Fiat Payment: - value: - data: - data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - verification: - avs: D - cvv: not_requested - threeDSecure: pass - eci: '00' - originalPayment: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - captured: false - captureAmount: - amount: '3.14' - currency: USD - captureDate: '2020-04-10T02:13:30.000Z' - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - description: Payment - status: pending - createDate: '2020-04-10T02:13:30.000Z' - refunds: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - originalPayment: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - refunds: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: refund - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - originalPayment: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - description: Payment - status: pending - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - trackingRef: '24910599141085313498894' - externalRef: YYYYMMDDXXXXXXXX012345 - errorCode: payment_failed - metadata: - email: satoshi@circle.com - phoneNumber: '+14155555555' - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - riskEvaluation: - decision: approved - reason: '3000' - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - Crypto Payment: - value: - data: - id: 66c56b6a-fc79-338b-8b94-aacc4f0f18de - type: payment - status: paid - amount: - amount: '1.00' - currency: USD - fees: - amount: '0.01' - currency: USD - 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' - createDate: '2022-07-21T20:16:35.092852Z' - updateDate: '2022-07-21T20:19:24.719313Z' - '401': - $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' -components: - securitySchemes: - bearerAuth: - type: http - scheme: bearer - parameters: - From: - name: from - description: Queries items created since the specified date-time (inclusive). - in: query - required: false - schema: - type: string - format: date-time - example: '2020-04-10T02:13:30.000Z' - To: - name: to - description: Queries items created before the specified date-time (inclusive). - in: query - required: false - schema: - type: string - format: date-time - example: '2020-04-10T02:13:30.000Z' - PageBefore: - name: pageBefore - description: 'A collection ID value used for pagination. - - - It marks the exclusive end of a page. When provided, the collection resource - will return the next `n` items before - - the id, with `n` being specified by `pageSize`. - - - The items will be returned in the natural order of the collection. - - - The resource will return the first page if neither `pageAfter` nor `pageBefore` - are specified. - - - SHOULD NOT be used in conjuction with pageAfter. - - ' - in: query - required: false - schema: - type: string - PageAfter: - name: pageAfter - description: 'A collection ID value used for pagination. - - - It marks the exclusive begin of a page. When provided, the collection resource - will return the next `n` items after - - the id, with `n` being specified by `pageSize`. - - - The items will be returned in the natural order of the collection. - - - The resource will return the first page if neither `pageAfter` nor `pageBefore` - are specified. - - - SHOULD NOT be used in conjuction with pageBefore. - - ' - in: query - required: false - schema: - type: string - PageSize: - name: pageSize - description: 'Limits the number of items to be returned. - - - Some collections have a strict upper bound that will disregard this value. - In case the specified value is higher - - than the allowed limit, the collection limit will be used. - - - If avoided, the collection will determine the page size itself. - - ' - in: query - required: false - schema: - type: integer - minimum: 1 - example: 5 - IdPath: - name: id - description: Universally unique identifier (UUID v4) of a resource. - in: path - required: true - schema: - type: string - format: uuid - example: b3d9d2d5-4c12-4946-a09d-953e82fae2b0 - Source: - name: source - description: Universally unique identifier (UUID v4) for the source. Filters - results to fetch only payments made from the provdided source. - in: query - required: false - schema: - type: string - format: uuid - example: b3d9d2d5-4c12-4946-a09d-953e82fae2b0 - SettlementId: - name: settlementId - description: Queries items with the specified settlement id. Matches any settlement - id if unspecified. - in: query - required: false - schema: - type: string - format: uuid - example: b48c8962-8e9f-40c3-9f1d-d9adde2ffe61 - PaymentIntentId: - name: paymentIntentId - description: Queries items with the specified payment intent id. - in: query - required: false - schema: - type: string - format: uuid - example: b48c8962-8e9f-40c3-9f1d-d9adde2ffe61 - PaymentSourceType: - name: type - description: Source account type. Filters the results to fetch all payments - made from a specified account type. Matches any source type if unspecified. - in: query - required: false - schema: - type: array - items: - type: string - enum: - - card - - wire - - ach - - sepa - PaymentStatus: - name: status - description: Queries items with the specified status. Matches any status if - unspecified. - in: query - required: false - schema: - type: string - enum: - - pending - - confirmed - - paid - - failed - - action_required - headers: - XRequestId: - description: Universally unique identifier (UUID v4) for the request. Helpful - for identifying a request when communicating with Circle support. - schema: - type: string - format: uuid - example: 2adba88e-9d63-44bc-b975-9b6ae3440dde - schemas: - IdempotencyKey: - type: string - description: Universally unique identifier (UUID v4) idempotency key. This key - is utilized to ensure exactly-once execution of mutating requests. - format: uuid - example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - CryptoPaymentsMoney: - type: object - required: - - amount - - currency - properties: - amount: - description: Magnitude of the amount, in units of the currency, with a `.`. - type: string - example: '3.14' - currency: - description: Currency code. - type: string - enum: - - USD - - ETH - - BTC - Chain: - type: string - description: A blockchain that a given currency is available on. - enum: - - ALGO - - AVAX - - BTC - - ETH - - FLOW - - HBAR - - MATIC - - SOL - - TRX - - XLM - PaymentMethodBlockchain: - type: object - required: - - type - - chain - properties: - type: - type: string - enum: - - blockchain - chain: - $ref: '#/components/schemas/Chain' - address: - type: string - readOnly: true - example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - PaymentIntentFees: - type: object - readOnly: true - required: - - type - - amount - - currency - properties: - type: - type: string - enum: - - blockchainLeaseFee - - totalPaymentFees - amount: - description: Magnitude of the amount, in units of the currency, with a `.`. - type: string - example: '3.14' - currency: - description: Currency code. - type: string - enum: - - USD - Timeline: - type: object - readOnly: true - required: - - status - - time - properties: - status: - type: string - enum: - - created - - pending - - complete - - expired - - failed - context: - type: string - enum: - - underpaid - - paid - - overpaid - time: - description: ISO-8601 UTC date/time format. - type: string - format: date-time - UtcTimestampReadOnly: - type: string - readOnly: true - description: ISO-8601 UTC date/time format. - example: '2020-04-10T02:13:30.000Z' - PaymentIntent: - type: object - required: - - idempotencyKey - - amount - - settlementCurrency - - paymentMethods - properties: - idempotencyKey: - $ref: '#/components/schemas/IdempotencyKey' - id: - type: string - readOnly: true - description: Unique system generated identifier for the entity. - format: uuid - example: b8627ae8-732b-4d25-b947-1df8f4007a29 - amount: - $ref: '#/components/schemas/CryptoPaymentsMoney' - amountPaid: - description: Sum of the the amount paid. - type: object - readOnly: true - required: - - amount - - currency - properties: - amount: - description: Magnitude of the amount, in units of the currency, with - a `.`. - type: string - example: '3.14' - currency: - description: Currency code. - type: string - enum: - - USD - settlementCurrency: - description: Desired currency for the payments to settle in. - type: string - enum: - - USD - - BTC - - ETH - paymentMethods: - type: array - items: - $ref: '#/components/schemas/PaymentMethodBlockchain' - fees: - type: array - readOnly: true - items: - $ref: '#/components/schemas/PaymentIntentFees' - paymentIds: - description: List of associated payments. - type: array - readOnly: true - items: - type: string - format: uuid - example: 69808f36-3e5e-4f37-bf82-ca79e4d70fc1 - timeline: - description: State management timeline. - type: array - readOnly: true - items: - $ref: '#/components/schemas/Timeline' - expiresOn: - $ref: '#/components/schemas/UtcTimestampReadOnly' - updateDate: - $ref: '#/components/schemas/UtcTimestampReadOnly' - createDate: - $ref: '#/components/schemas/UtcTimestampReadOnly' - Id: - type: string - description: Unique system generated identifier for the entity. - format: uuid - example: b8627ae8-732b-4d25-b947-1df8f4007a29 - IdMerchant: - type: string - description: Unique system generated identifier for the merchant. - format: uuid - example: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - MerchantWalletId: - type: string - description: Unique system generated identifier for the wallet of the merchant. - maxLength: 36 - example: '212000' - FiatMoneyUsd: - type: object - required: - - amount - - currency - properties: - amount: - description: Magnitude of the amount, in units of the currency, with a `.`. - type: string - example: '3.14' - currency: - description: Currency code. - type: string - enum: - - USD - SourceResponse: - type: object - description: The payment source. - properties: - id: - $ref: '#/components/schemas/Id' - type: - type: string - description: Type of the source. - enum: - - card - - ach - - wire - - sepa - PaymentStatus: - type: string - description: Enumerated status of the payment. `pending` means the payment is - waiting to be processed. `confirmed` means the payment has been approved by - the bank and the merchant can treat it as successful, but settlement funds - are not yet available to the merchant. `paid` means settlement funds have - been received and are available to the merchant. `failed` means something - went wrong (most commonly that the payment was denied). `action_required` - means that additional steps are required to process this payment; refer to - `requiredAction` for more details. Terminal states are `paid` and `failed`. - enum: - - pending - - confirmed - - paid - - failed - - action_required - UtcTimestamp: - type: string - description: ISO-8601 UTC date/time format. - example: '2020-04-10T02:13:30.000Z' - RequiredAction: - type: object - description: When the payment status is `action_required`, this object summarizes - the required additional steps. - required: - - type - - redirectUrl - properties: - type: - type: string - description: The type of action that is required to proceed with the payment. - Currently only one type is supported. - enum: - - three_d_secure_required - redirectUrl: - type: string - description: The URL to bring the user to in order to complete the payment. - example: https://example.org - CancelRefundReversalStatus: - type: string - enum: - - pending - - confirmed - - paid - - failed - description: Enumerated status of the payment. `pending` means the payment is - waiting to be processed. `confirmed` means the payment has been approved by - the bank and the merchant can treat it as successful, but settlement funds - are not yet available to the merchant. `paid` means settlement funds have - been received and are available to the merchant. `failed` means something - went wrong (most commonly that the payment was denied). Terminal states are - `paid` and `failed`. - PaymentInfoCancel: - type: object - description: Status information of the related cancel. This property is only - present on canceled payment or refund items. - nullable: true - properties: - id: - $ref: '#/components/schemas/Id' - type: - type: string - description: Type of the payment object. - enum: - - cancel - description: - description: Enumerated description of the payment item. - type: string - nullable: true - enum: - - Payment - status: - $ref: '#/components/schemas/CancelRefundReversalStatus' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - PaymentInfoPaymentAndRefund: - type: object - description: Status information of the related payment. This property is only - present on refund or cancel items. - properties: - id: - $ref: '#/components/schemas/Id' - type: - type: string - description: Type of the payment object. - enum: - - payment - - refund - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - description: - type: string - description: Enumerated description of the payment item. - nullable: true - enum: - - Payment - status: - $ref: '#/components/schemas/PaymentStatus' - requiredAction: - $ref: '#/components/schemas/RequiredAction' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - Channel: - type: string - format: uuid - description: The channel identifier that can be set for the payment. When not - provided, the default channel is used. - example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - FiatPayment: - type: object - description: Status information of the related payment. This property is only - present on refund or cancel items. - required: - - id - - type - - merchantId - - amount - - source - - status - properties: - id: - $ref: '#/components/schemas/Id' - type: - description: Type of the payment object. - type: string - enum: - - payment - merchantId: - $ref: '#/components/schemas/IdMerchant' - merchantWalletId: - $ref: '#/components/schemas/MerchantWalletId' - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - source: - $ref: '#/components/schemas/SourceResponse' - description: - description: Enumerated description of the payment. - type: string - enum: - - Payment - status: - $ref: '#/components/schemas/PaymentStatus' - captured: - description: Determines if a payment has successfully been captured. This - property is only present for payments that did not use auto capture. - type: boolean - captureAmount: - $ref: '#/components/schemas/FiatMoneyUsd' - captureDate: - $ref: '#/components/schemas/UtcTimestamp' - requiredAction: - $ref: '#/components/schemas/RequiredAction' - cancel: - $ref: '#/components/schemas/PaymentInfoCancel' - refunds: - type: array - items: - $ref: '#/components/schemas/PaymentInfoPaymentAndRefund' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - channel: - $ref: '#/components/schemas/Channel' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - updateDate: - $ref: '#/components/schemas/UtcTimestamp' - CryptoPayment: - type: object - description: Status information of the related payment. This property is only - present on refund or cancel items. - required: - - id - - type - - merchantId - - amount - - source - - status - properties: - id: - $ref: '#/components/schemas/Id' - type: - description: Type of the payment object. - type: string - enum: - - payment - merchantId: - $ref: '#/components/schemas/IdMerchant' - merchantWalletId: - $ref: '#/components/schemas/MerchantWalletId' - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - status: - $ref: '#/components/schemas/PaymentStatus' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - paymentIntentId: - type: string - format: uuid - example: 6e4d4047-db14-4c09-b238-1215aee50d03 - settlementAmount: - $ref: '#/components/schemas/FiatMoneyUsd' - depositAddress: - type: object - properties: - chain: - $ref: '#/components/schemas/Chain' - address: - type: string - example: '0x97de855690955e0da79ce5c1b6804847e7070c7f' - transactionHash: - type: string - example: '0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - updateDate: - $ref: '#/components/schemas/UtcTimestamp' - FiatCancel: - type: object - description: Status information of the related cancel. This property is only - present on canceled payment or refund items. - nullable: true - required: - - id - - type - - merchantId - - amount - - source - - status - properties: - id: - $ref: '#/components/schemas/Id' - type: - type: string - description: Type of the payment object. - enum: - - cancel - merchantId: - $ref: '#/components/schemas/IdMerchant' - merchantWalletId: - $ref: '#/components/schemas/MerchantWalletId' - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - source: - $ref: '#/components/schemas/SourceResponse' - description: - description: Enumerated description of the payment. - type: string - enum: - - Payment - status: - $ref: '#/components/schemas/CancelRefundReversalStatus' - originalPayment: - $ref: '#/components/schemas/PaymentInfoPaymentAndRefund' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - channel: - $ref: '#/components/schemas/Channel' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - updateDate: - $ref: '#/components/schemas/UtcTimestamp' - FiatRefund: - type: object - required: - - id - - type - - merchantId - - amount - - source - - status - properties: - id: - $ref: '#/components/schemas/Id' - type: - description: Type of the payment object. - type: string - enum: - - refund - merchantId: - $ref: '#/components/schemas/IdMerchant' - merchantWalletId: - $ref: '#/components/schemas/MerchantWalletId' - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - source: - $ref: '#/components/schemas/SourceResponse' - description: - description: Enumerated description of the payment. - type: string - enum: - - Payment - status: - $ref: '#/components/schemas/CancelRefundReversalStatus' - originalPayment: - $ref: '#/components/schemas/PaymentInfoPaymentAndRefund' - cancel: - $ref: '#/components/schemas/PaymentInfoCancel' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - channel: - $ref: '#/components/schemas/Channel' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - updateDate: - $ref: '#/components/schemas/UtcTimestamp' - AvsResults: - type: string - description: Status of the AVS check. Raw AVS response, expressed as an upper-case - letter. `not_requested` indicates check was not made. `pending` is pending/processing. - example: D - CvvResults: - description: Enumerated status of the check. `not_requested` indicates check - was not made. `pass` indicates value is correct. `fail` indicates value is - incorrect. `unavailable` indicates card issuer did not do the provided check. - `pending` indicates check is pending/processing. - type: string - enum: - - not_requested - - pass - - fail - - unavailable - - pending - ThreeDsResult: - type: string - description: Enumerated status of the check. `pass` indicates successful 3DS - authentication. `fail` indicates failed 3DS authentication. - enum: - - pass - - fail - Eci: - type: string - description: ECI (electronic commerce indicator) value returned by Directory - Servers (namely Visa, MasterCard, JCB, and American Express) indicating the - outcome of authentication attempted on transactions enforced by 3DS. - enum: - - '00' - - '01' - - '02' - - '05' - - '06' - - '07' - PaymentVerificationResponse: - type: object - description: Indicates the status of the payment verification. This property - will be present once the payment is confirmed. - required: - - avs - - cvv - properties: - avs: - $ref: '#/components/schemas/AvsResults' - cvv: - $ref: '#/components/schemas/CvvResults' - threeDSecure: - $ref: '#/components/schemas/ThreeDsResult' - eci: - $ref: '#/components/schemas/Eci' - ExternalRef: - type: string - description: "External network identifier which will be present once provided\ - \ from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability\ - \ Data (IMAD/OMAD)**: unique number given to each FedWire payment when using\ - \ the Federal Reserve Bank Service which can be used to investigate and track\ - \ wire transfers.\n" - example: YYYYMMDDXXXXXXXX012345 - PaymentErrorCode: - type: string - description: Indicates the failure reason of a payment. Only present for payments - in failed state. Possible values are [`payment_failed`, `payment_fraud_detected`, - `payment_denied`, `payment_not_supported_by_issuer`, `payment_not_funded`, - `payment_unprocessable`, `payment_stopped_by_issuer`, `payment_canceled`, - `payment_returned`, `payment_failed_balance_check`, `card_failed`, `card_invalid`, - `card_address_mismatch`, `card_zip_mismatch`, `card_cvv_invalid`, `card_expired`, - `card_limit_violated`, `card_not_honored`, `card_cvv_required`, `credit_card_not_allowed`, - `card_account_ineligible`, `card_network_unsupported`, `channel_invalid`, - `unauthorized_transaction`, `bank_account_ineligible`, `bank_transaction_error`, - `invalid_account_number`, `invalid_wire_rtn`, `invalid_ach_rtn`, `vendor_inactive`]' - nullable: true - enum: - - payment_failed - - payment_fraud_detected - - payment_denied - - payment_not_supported_by_issuer - - payment_not_funded - - payment_unprocessable - - payment_stopped_by_issuer - - payment_canceled - - payment_returned - - payment_failed_balance_check - - card_failed - - card_invalid - - card_address_mismatch - - card_zip_mismatch - - card_cvv_invalid - - card_expired - - card_limit_violated - - card_not_honored - - card_cvv_required - - card_restricted, - - card_account_ineligible - - card_network_unsupported - - channel_invalid - - unauthorized_transaction - - bank_account_ineligible - - bank_transaction_error - - invalid_account_number - - invalid_wire_rtn - - invalid_ach_rtn - - ref_id_invalid - - account_name_mismatch - - account_number_mismatch - - account_ineligible - - wallet_address_mismatch - - customer_name_mismatch - - institution_name_mismatch - - vendor_inactive - Email: - type: string - description: Email of the user. - maxLength: 1024 - example: satoshi@circle.com - PhoneNumber: - type: string - description: Phone number of the user in E.164 format. We recommend using a - library such as [libphonenumber](https://github.com/google/libphonenumber) - to parse and validate phone numbers. - maxLength: 16 - pattern: /\+?[1-9]\d{1,14}/ - example: '+14155555555' - MetadataPhoneEmail: - type: object - required: - - email - properties: - email: - $ref: '#/components/schemas/Email' - phoneNumber: - $ref: '#/components/schemas/PhoneNumber' - RiskEvaluation: - type: object - description: Results of risk evaluation. Only present if the payment is denied - by Circle's risk service. - nullable: true - properties: - decision: - description: Enumerated decision of the account. - type: string - enum: - - approved - - denied - - review - reason: - description: Risk reason for the definitive decision outcome. - type: string - nullable: true - example: '3000' - FiatPaymentPolymorphic: - type: object - required: - - id - - type - - merchantId - - amount - - source - - status - properties: - id: - $ref: '#/components/schemas/Id' - type: - description: Type of the payment object. - type: string - enum: - - payment - - refund - - cancel - merchantId: - $ref: '#/components/schemas/IdMerchant' - merchantWalletId: - $ref: '#/components/schemas/MerchantWalletId' - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - source: - $ref: '#/components/schemas/SourceResponse' - description: - description: Enumerated description of the payment. - type: string - enum: - - Payment - status: - $ref: '#/components/schemas/PaymentStatus' - requiredAction: - $ref: '#/components/schemas/RequiredAction' - verification: - $ref: '#/components/schemas/PaymentVerificationResponse' - originalPayment: - $ref: '#/components/schemas/FiatPayment' - cancel: - $ref: '#/components/schemas/FiatCancel' - refunds: - type: array - nullable: true - items: - $ref: '#/components/schemas/FiatRefund' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - trackingRef: - description: Payment tracking reference. Will be present once known. - type: string - nullable: true - example: '24910599141085313498894' - externalRef: - $ref: '#/components/schemas/ExternalRef' - errorCode: - $ref: '#/components/schemas/PaymentErrorCode' - metadata: - $ref: '#/components/schemas/MetadataPhoneEmail' - channel: - $ref: '#/components/schemas/Channel' - riskEvaluation: - $ref: '#/components/schemas/RiskEvaluation' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - updateDate: - $ref: '#/components/schemas/UtcTimestamp' - responses: - NotAuthorized: - description: The request has not been applied because it lacks valid authentication - credentials. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - type: object - title: NotAuthorized - required: - - code - - message - properties: - code: - type: integer - example: 400 - message: - type: string - example: Something went wrong. - example: - code: 401 - message: Malformed authorization. - examples: - response: - value: - code: 401 - message: Malformed authorization. - BadRequest: - description: The request cannot be processed due to a client error. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - type: object - title: BadRequest - required: - - code - - message - properties: - code: - type: integer - example: 400 - message: - type: string - example: Something went wrong. - example: - code: 400 - message: Bad request. - examples: - response: - value: - code: 400 - message: Bad request. - NotFound: - description: The specified resource was not found. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - type: object - title: NotFound - required: - - code - - message - properties: - code: - type: integer - example: 400 - message: - type: string - example: Something went wrong. - example: - code: 404 - message: Not found. - examples: - response: - value: - code: 404 - message: Not found. diff --git a/openapi/yaml/general.yaml b/openapi/yaml/general.yaml index 1972e38..dc914cc 100644 --- a/openapi/yaml/general.yaml +++ b/openapi/yaml/general.yaml @@ -1,8 +1,8 @@ openapi: 3.0.2 servers: -- url: api-sandbox.circle.com +- url: https://api-sandbox.circle.com info: - version: 1.0.3 + version: 1.1.0 title: API Overview description: Common endpoints shared across all Circle APIs. tags: @@ -97,38 +97,6 @@ paths: keyId: key1 publicKey: LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWSBCTE9DSy0tLS0tClZlcnNpb246IEJDUEcgdjEuNTQKCm1RRU5CRjAxdmk0QkNBQ3JzMDNLS1Y0Qk9SRkYyT0Z4bUdvb0UyaTZMbnNneE5UL1dsV2s1ZTl2RDd2NENkSm0KcGJJbENmZ0U4WFlnYmhKUTE4YStaTzlPM0RFYUp2dGhJSEtjL0l1UEIvZmdEYUJUT285NkJzL2pVRFp6ZGxaVApQazNFUjliNFZPeGVwMFNPSHFMcmxTVFY4ZXB3M1R3SEdaL3NpSWdBYXEwRGdJdlZxUTY4TGVaMnorUFJWZm04CmhhSnJpb05SRU5Ja2ZNTWY5aFdySlowSW1zUk1aVmpDMVVrd2FSSHdrTTMwQUlia1dYcFJ5R205SXhQaXdGa08Kb1RnWlpwUFpsdVczckdkWER0NHZqL24za09hczV1dFdoNFovMlhjWHBiSUUyU0FPK0hycUdIclRnK1ZmZ05JNwpZcVZqYW5MOEN1bm83UkxmcDhKZlZDNXBLUm5ySVNCTnphN1ZBQkVCQUFHMEJrTnBjbU5zWllrQkhBUVFBUWtBCkJnVUNYVFcrTGdBS0NSQ3EzaHNwWjBMeGEwdnpCLzQvQTJpdk1CWW1aZXV2bEJZMm5ZZnNXek9Sb28vU3BIYkQKY2Y0UmtxZzZ0RERJSkUzNHhDVit0MzJydmJkM0ZOdVZseWs1MDVZRkpESnI4cVc2S0tkQVRXdU16eW5mMVVoUAo1M25hTlc0cXdrdSt3b0RWWjJpci9lUVI1WUc4L0RGcnd3bXdaa0dRd0Ftc3h5ZHd5anBnLzBrQ3lpZHkxdVBkCmVVWGgwdWt4dS9Dais4UFl5cHcwdit5V2tzbjdSZ2dVbkJFMWhiQ2pEV3FweHZjMEpDNVAxdmx6L2xRcWQrR3oKRC9Td1FJTVdRVElnV3BHRVVvQTRDc3drbU5PdHhsRVF1U0tueXNtTG02S0ExUmRhTzd6V2IrdWNLN21FZ2VoSwpXU2hHZExqRVNNZlVRUTczemNqMXg2amxLUFNhRlJyLzhXcHhrVXYzVHYvQzZMb0JpejRLCj1WSWg3Ci0tLS0tRU5EIFBHUCBQVUJMSUMgS0VZIEJMT0NLLS0tLS0K /v1/notifications/subscriptions: - get: - security: - - bearerAuth: [] - summary: List all notification subscriptions - description: Retrieve a list of existing notification subscriptions with details. - parameters: [] - operationId: listSubscriptions - tags: - - Subscriptions - responses: - '200': - description: Successfully retrieved a list of notification subscriptions. - content: - application/json: - schema: - title: ListSubscriptionsResponse - properties: - data: - type: array - items: - $ref: '#/components/schemas/SubscriptionResponse' - examples: - response: - value: - data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - endpoint: https://example.org/handler/for/notifications - subscriptionDetails: - - url: arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17 - status: confirmed - '401': - $ref: '#/components/responses/NotAuthorized' post: security: - bearerAuth: [] @@ -141,7 +109,7 @@ paths: requests will be rejected with a Limit Exceeded error. ' - operationId: createSubscribtion + operationId: createSubscription tags: - Subscriptions requestBody: @@ -155,7 +123,7 @@ paths: content: application/json: schema: - title: CreateSubscribtionResponse + title: CreateSubscriptionResponse properties: data: $ref: '#/components/schemas/SubscriptionResponse' @@ -174,6 +142,38 @@ paths: $ref: '#/components/responses/NotAuthorized' '429': $ref: '#/components/responses/LimitExceeded' + get: + security: + - bearerAuth: [] + summary: List all notification subscriptions + description: Retrieve a list of existing notification subscriptions with details. + parameters: [] + operationId: listSubscriptions + tags: + - Subscriptions + responses: + '200': + description: Successfully retrieved a list of notification subscriptions. + content: + application/json: + schema: + title: ListSubscriptionsResponse + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionResponse' + examples: + response: + value: + data: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + endpoint: https://example.org/handler/for/notifications + subscriptionDetails: + - url: arn:aws:sns:us-east-1:<...>:fcb4a2c9-9c4f-4706-b312-6b22650f5d17 + status: confirmed + '401': + $ref: '#/components/responses/NotAuthorized' /v1/notifications/subscriptions/{id}: delete: parameters: @@ -184,7 +184,7 @@ paths: description: To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed. - operationId: deleteSubscribtion + operationId: deleteSubscription tags: - Subscriptions responses: @@ -196,7 +196,7 @@ paths: content: application/json: schema: - title: DeleteSubscribtionResponse + title: DeleteSubscriptionResponse properties: data: $ref: '#/components/schemas/UnsubscribeResponse' diff --git a/openapi/yaml/payments.yaml b/openapi/yaml/payments.yaml index 8e391d7..a230b28 100644 --- a/openapi/yaml/payments.yaml +++ b/openapi/yaml/payments.yaml @@ -1,23 +1,193 @@ openapi: 3.0.2 servers: -- url: api-sandbox.circle.com +- url: https://api-sandbox.circle.com info: - version: 1.0.3 + version: 1.1.0 title: Payments API - description: APIs for accepting payments. + description: 'The Circle Payments API allows you to take payments from your end + users via traditional methods such as debit & credit cards, bank accounts (wires + and ACH), etc., and receive settlement in USDC. + + + The Circle Payments API has been designed with any business or internet commerce + in mind, not just crypto applications, and it''s based on Circle''s extensive + experience processing millions of card payments since 2014. + + ' tags: - name: Payments -- name: On-chain payments + description: Create, cancel, refund, and get updates on card and ACH payments. +- name: Crypto Payment Intents + description: Create and track intent for end user to pay via crypto. - name: Cards + description: Link, update, and get information on debit/credit cards. +- name: Payment Tokens + description: Create Apple Pay and Google Pay payment tokens. - name: Wires + description: Create, get instructions, and get information on bank accounts for + wire transfers. - name: ACH + description: Link and get information on bank account for ACH payments. - name: SEPA + description: Create and get information on SEPA accounts. - name: Settlements + description: Get information on settlement batches. - name: Chargebacks + description: Get information on card chargebacks. - name: Reversals + description: Get information on ACH reversals. - name: Balances + description: Get information on settled and unsettled balances. paths: /v1/payments: + post: + security: + - bearerAuth: [] + summary: Create a payment + operationId: createPayment + tags: + - Payments + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PaymentCreationRequest' + responses: + '201': + description: Successfully created a payment. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: CreatePaymentResponse + properties: + data: + $ref: '#/components/schemas/DetailedPayment' + examples: + response: + value: + data: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: payment + merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 + merchantWalletId: '212000' + amount: + amount: '3.14' + currency: USD + source: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: card + description: Payment + status: pending + captured: false + captureAmount: + amount: '3.14' + currency: USD + captureDate: '2020-04-10T02:13:30.000Z' + requiredAction: + type: three_d_secure_required + redirectUrl: https://example.org + verification: + avs: D + cvv: not_requested + threeDSecure: pass + eci: '00' + cancel: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: cancel + merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 + merchantWalletId: '212000' + amount: + amount: '3.14' + currency: USD + source: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: card + description: Payment + status: pending + originalPayment: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: payment + amount: + amount: '3.14' + currency: USD + description: Payment + status: pending + requiredAction: + type: three_d_secure_required + redirectUrl: https://example.org + fees: + amount: '3.14' + currency: USD + createDate: '2020-04-10T02:13:30.000Z' + fees: + amount: '3.14' + currency: USD + channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + refunds: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: refund + merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 + merchantWalletId: '212000' + amount: + amount: '3.14' + currency: USD + source: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: card + description: Payment + status: pending + originalPayment: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: payment + amount: + amount: '3.14' + currency: USD + description: Payment + status: pending + requiredAction: + type: three_d_secure_required + redirectUrl: https://example.org + fees: + amount: '3.14' + currency: USD + createDate: '2020-04-10T02:13:30.000Z' + cancel: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + type: cancel + description: Payment + status: pending + createDate: '2020-04-10T02:13:30.000Z' + fees: + amount: '3.14' + currency: USD + channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + fees: + amount: '3.14' + currency: USD + trackingRef: '24910599141085313498894' + errorCode: payment_failed + metadata: + email: satoshi@circle.com + phoneNumber: '+14155555555' + riskEvaluation: + decision: approved + reason: '3000' + channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' get: security: - bearerAuth: [] @@ -174,170 +344,22 @@ paths: fees: amount: '0.00' currency: USD - createDate: '2022-04-21T12:49:21.146Z' - updateDate: '2022-04-21T12:54:10.596976Z' - merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b - merchantWalletId: '1000174786' - source: - id: 45fa5524-41b9-48ca-94cd-f45cb36cce4d - type: card - originalPayment: - id: 895f8db5-1d8c-407d-9533-b5ca3fbcc74e - type: payment - status: paid - createDate: '2022-04-06T19:33:29.690Z' - updateDate: '2022-04-06T19:47:23.681180Z' - reason: requested_by_customer - '401': - $ref: '#/components/responses/NotAuthorized' - post: - security: - - bearerAuth: [] - summary: Create a payment - operationId: createPayment - tags: - - Payments - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentCreationRequest' - responses: - '201': - description: Successfully created a payment. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: CreatePaymentResponse - properties: - data: - $ref: '#/components/schemas/DetailedPayment' - examples: - response: - value: - data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - captured: false - captureAmount: - amount: '3.14' - currency: USD - captureDate: '2020-04-10T02:13:30.000Z' - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - verification: - avs: D - cvv: not_requested - threeDSecure: pass - eci: '00' - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - originalPayment: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - refunds: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: refund - merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 - merchantWalletId: '212000' - amount: - amount: '3.14' - currency: USD - source: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: card - description: Payment - status: pending - originalPayment: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: payment - amount: - amount: '3.14' - currency: USD - description: Payment - status: pending - requiredAction: - type: three_d_secure_required - redirectUrl: https://example.org - fees: - amount: '3.14' - currency: USD - createDate: '2020-04-10T02:13:30.000Z' - cancel: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - type: cancel - description: Payment - status: pending - createDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - fees: - amount: '3.14' - currency: USD - trackingRef: '24910599141085313498894' - errorCode: payment_failed - metadata: - email: satoshi@circle.com - phoneNumber: '+14155555555' - riskEvaluation: - decision: approved - reason: '3000' - channel: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - createDate: '2020-04-10T02:13:30.000Z' - updateDate: '2020-04-10T02:13:30.000Z' - '400': - $ref: '#/components/responses/BadRequest' + createDate: '2022-04-21T12:49:21.146Z' + updateDate: '2022-04-21T12:54:10.596976Z' + merchantId: b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b + merchantWalletId: '1000174786' + source: + id: 45fa5524-41b9-48ca-94cd-f45cb36cce4d + type: card + originalPayment: + id: 895f8db5-1d8c-407d-9533-b5ca3fbcc74e + type: payment + status: paid + createDate: '2022-04-06T19:33:29.690Z' + updateDate: '2022-04-06T19:47:23.681180Z' + reason: requested_by_customer '401': $ref: '#/components/responses/NotAuthorized' - '404': - $ref: '#/components/responses/NotFound' /v1/payments/{id}: get: parameters: @@ -366,7 +388,7 @@ paths: discriminator: propertyName: type mapping: - Fiat Payment: '#/components/schemas/FiatPayment' + Fiat Payment: '#/components/schemas/FiatPaymentPolymorphic' Crypto Payment: '#/components/schemas/CryptoPayment' examples: Fiat Payment: @@ -964,218 +986,247 @@ paths: $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' - /v1/transfers: + /v1/paymentIntents: + post: + security: + - bearerAuth: [] + summary: Create a payment intent + operationId: createPaymentIntent + tags: + - Crypto Payment Intents + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PaymentIntent' + responses: + '201': + description: Successfully created a payment intent. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: CreatePaymentIntentResponse + properties: + data: + $ref: '#/components/schemas/PaymentIntent' + examples: + response: + value: + data: + id: 8755d0ea-14f9-4259-b092-de23c14b6568 + amount: + amount: '3.14' + 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' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' get: security: - bearerAuth: [] + summary: List all payment intents + operationId: listPaymentIntents + tags: + - Crypto Payment Intents parameters: - - name: walletId - description: Unique identifier for the source or destination wallet of transfers, - if any. May not be used in conjunction with destinationWalletId or sourceWalletId. - Useful for fetching all transfers related to a wallet. - in: query - required: false - schema: - type: string - example: '12345' - - name: sourceWalletId - description: Unique identifier for the source wallet of transfers, if any. + - name: status + description: Filters by the most recent `timeline.status` within the payment + intent. in: query required: false schema: type: string - example: '12345' - - name: destinationWalletId - description: Unique identifier for the destination wallet of transfers, if - any. + enum: + - created + - pending + - complete + - expired + - failed + - name: context + description: Filters by the most recent `timeline.context` within the payment + intent. in: query required: false schema: type: string - example: '12345' - - $ref: '#/components/parameters/ReturnIdentities' + enum: + - underpaid + - paid + - overpaid - $ref: '#/components/parameters/From' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/PageBefore' - $ref: '#/components/parameters/PageAfter' - $ref: '#/components/parameters/PageSize' - summary: List all transfers - description: Searches for transfers involving the provided wallets. If no wallet - ids are provided, searches all wallets associated with your Circle API account. - If the date parameters are omitted, returns the most recent transfers. This - endpoint returns up to 50 transfers in descending chronological order or pageSize, - if provided. - operationId: listTransfers - tags: - - On-chain payments responses: '200': - description: Successfully retrieved a list of transfers. + description: Successfully retrieved a list of payment intents. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListTransfersResponse + title: ListPaymentIntentsResponse properties: data: type: array items: - $ref: '#/components/schemas/Transfer' + $ref: '#/components/schemas/PaymentIntent' examples: response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - source: - type: wallet - id: '12345' - destination: - type: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: '123456789' - chain: ALGO amount: amount: '3.14' currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' - status: pending + amountPaid: + amount: '3.14' + currency: USD + settlementCurrency: USD + paymentMethods: + - type: blockchain + chain: ALGO + address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + fees: + - type: blockchainLeaseFee + amount: '3.14' + currency: USD + paymentIds: + - 69808f36-3e5e-4f37-bf82-ca79e4d70fc1 + timeline: + - status: created + context: underpaid + time: '2020-04-10T02:13:30.000Z' + expiresOn: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' '401': $ref: '#/components/responses/NotAuthorized' - /v1/transfers/{id}: + /v1/paymentIntents/{id}: get: - parameters: - - $ref: '#/components/parameters/IdPath' - - $ref: '#/components/parameters/ReturnIdentities' security: - bearerAuth: [] - summary: Get a transfer - operationId: getTransfer + summary: Get a payment intent + operationId: getPaymentIntent tags: - - On-chain payments + - Crypto Payment Intents + parameters: + - $ref: '#/components/parameters/IdPath' responses: '200': + description: Successfully retrieved a payment intent. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' - description: Successfully retrieved a transfer. content: application/json: schema: - title: GetTransferResponse + title: GetPaymentIntentResponse properties: data: - $ref: '#/components/schemas/TransferDetailedTransfer' + $ref: '#/components/schemas/PaymentIntent' examples: response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - source: - type: wallet - id: '12345' - destination: - type: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH + id: 8755d0ea-14f9-4259-b092-de23c14b6568 amount: amount: '3.14' currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' - status: pending - createDate: '2020-04-10T02:13:30.000Z' - /v1/wallets/{walletId}/addresses: + 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' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + /v1/paymentIntents/{id}/expire: post: - parameters: - - $ref: '#/components/parameters/WalletId' security: - bearerAuth: [] - summary: Create a blockchain address - description: 'Generates a new blockchain address for a wallet for a given currency/chain - pair. Circle may reuse addresses on blockchains that support reuse. For example, - if you''re requesting two addresses for depositing USD and ETH, both on Ethereum, - you may see the same Ethereum address returned. Depositing cryptocurrency - to a generated address will credit the associated wallet with the value of - the deposit. - - ' - operationId: generateAddress + summary: Expire a payment intent + operationId: expirePaymentIntent tags: - - On-chain payments + - Crypto Payment Intents + parameters: + - $ref: '#/components/parameters/IdPath' requestBody: content: application/json: schema: - $ref: '#/components/schemas/GenerateAddressRequest' + type: object responses: '201': - description: Successfully generated a new address. - headers: - X-Request-Id: - $ref: '#/components/headers/XRequestId' - content: - application/json: - schema: - title: GenerateAddressResponse - properties: - data: - $ref: '#/components/schemas/AddressObject' - examples: - response: - value: - data: - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: '123456789' - currency: USD - chain: ALGO - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '409': - $ref: '#/components/responses/Conflict' - get: - security: - - bearerAuth: [] - parameters: - - $ref: '#/components/parameters/WalletId' - - $ref: '#/components/parameters/From' - - $ref: '#/components/parameters/To' - - $ref: '#/components/parameters/PageBefore' - - $ref: '#/components/parameters/PageAfter' - - $ref: '#/components/parameters/PageSize' - summary: List all addresses - description: Retrieves a list of addresses associated with a wallet. - operationId: listAddresses - tags: - - On-chain payments - responses: - '200': - description: Successfully retrieved a list of addresses. + description: Successfully expired a payment intent. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListAddressesResponse + title: ExpirePaymentIntentResponse properties: data: - type: array - items: - $ref: '#/components/schemas/AddressObject' + $ref: '#/components/schemas/PaymentIntent' examples: response: value: data: - - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: '123456789' - currency: USD - chain: ALGO + id: 8755d0ea-14f9-4259-b092-de23c14b6568 + amount: + amount: '3.14' + currency: USD + amountPaid: + amount: '3.14' + currency: USD + settlementCurrency: USD + paymentMethods: + - type: blockchain + chain: ETH + paymentIds: [] + timeline: + - status: expired + context: underpaid + reason: requested_by_merchant + time: '2022-07-21T21:45:54.569Z' + - status: created + time: '2022-07-21T20:13:35.579331Z' + createDate: '2022-07-21T20:13:35.578678Z' + updateDate: '2022-07-21T20:19:24.859052Z' '400': $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' '404': $ref: '#/components/responses/NotFound' /v1/cards: @@ -1282,6 +1333,7 @@ paths: network: VISA bin: '401230' issuerCountry: US + fundingType: credit fingerprint: eb170539-9e1c-4e92-bf4f-1d09534fdca2 verification: avs: D @@ -1415,6 +1467,55 @@ paths: phoneNumber: '+14155555555' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + /v1/paymentTokens: + post: + security: + - bearerAuth: [] + summary: Create a payment token + description: Convert a digital wallet (Apple Pay, Google Pay) token to a single-use + payment token. + operationId: createPaymentToken + tags: + - Payment Tokens + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PaymentTokenRequest' + responses: + '201': + description: Successfully converted a digital token to a Circle token account. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: CreatePaymentTokenResponse + properties: + data: + $ref: '#/components/schemas/PaymentToken' + examples: + response: + value: + 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' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' /v1/banks/wires: post: security: @@ -1722,7 +1823,7 @@ paths: content: application/json: schema: - title: CreateAchAccountResponse + title: CreateMockAchAccountResponse properties: data: $ref: '#/components/schemas/MockAchAccountResponse' @@ -2032,6 +2133,7 @@ paths: paymentId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 reasonCode: '10.4' + status: active category: Canceled Recurring Payment history: - type: 1st Chargeback @@ -2080,6 +2182,7 @@ paths: paymentId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 merchantId: fc988ed5-c129-4f70-a064-e5beb7eb8e32 reasonCode: '10.4' + status: active category: Canceled Recurring Payment history: - type: 1st Chargeback @@ -2272,6 +2375,7 @@ components: required: false schema: type: array + uniqueItems: true items: type: string enum: @@ -2390,25 +2494,6 @@ components: type: string format: uuid example: b3d9d2d5-4c12-4946-a09d-953e82fae2b0 - ReturnIdentities: - name: returnIdentities - description: Specify if you would like to see identities in the response. Restricts - maximum returned items to 5. By default returnIdentities is false, resulting - in the response not returning `data.source.identities`. - in: query - required: false - schema: - type: boolean - example: 'true' - default: false - WalletId: - name: walletId - description: Identifier for the wallet. - in: path - required: true - schema: - type: string - example: 0123456789 PaymentId: name: paymentId description: The payment ID associated with the chargeback. @@ -3429,360 +3514,148 @@ components: - pending - processed - failed - IdentityAddress: - type: object - required: - - line1 - - city - - district - - postalCode - - country - properties: - line1: - type: string - description: Line one of the street address. - maxLength: 1024 - example: 100 Money Street - line2: - type: string - description: Line two of the street address. - maxLength: 1024 - example: Suite 1 - city: - type: string - description: City portion of the address. - maxLength: 1024 - example: Boston - district: - description: State / County / Province / Region portion of the address. - If the country is US or Canada, then district is required and should use - the two-letter code for the subdivision. - type: string - maxLength: 16 - example: MA - postalCode: - type: string - description: Postal / ZIP code of the address. - maxLength: 16 - example: '01234' - country: - type: string - description: Country portion of the address. Formatted as a two-letter country - code specified in ISO 3166-1 alpha-2. - maxLength: 2 - example: US - Identity: - type: object - description: "The identity of the originator. Identities are required when:\n\ - \ * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n\ - \ * `amount.amount` >= $3,000 in value\n" - required: - - type - - name - - addresses - properties: - type: - type: string - description: 'The type of identity for the originator. - - * `individual` - A uniquely distinguishable individual. - - * `business` - Any entity other than a natural person that can establish - a permanent customer relationship with an affected entity or otherwise - own property. This can include companies, foundations, anstalt, partnerships, - associations and other relevantly similar entities. - - ' - enum: - - individual - - business - name: - type: string - description: Full name of the identity. - example: Satoshi Nakamoto - maxLength: 1024 - addresses: - type: array - items: - $ref: '#/components/schemas/IdentityAddress' - TransferSourceWalletLocation: - description: A source wallet location. + CryptoPaymentsMoney: type: object required: - - type - - id + - amount + - currency properties: - type: - type: string - enum: - - wallet - id: + amount: + description: Magnitude of the amount, in units of the currency, with a `.`. type: string - description: The id of the wallet. - example: '12345' - identities: - type: array - items: - $ref: '#/components/schemas/Identity' - TransferSourceBlockchainLocation: - description: A source blockchain address. - type: object - required: - - type - - chain - properties: - type: + example: '3.14' + currency: + description: Currency code. type: string enum: - - blockchain - chain: - $ref: '#/components/schemas/Chain' - identities: - type: array - items: - $ref: '#/components/schemas/Identity' - TransferSourceLocation: - description: A source of funds. - oneOf: - - $ref: '#/components/schemas/TransferSourceWalletLocation' - - $ref: '#/components/schemas/TransferSourceBlockchainLocation' - discriminator: - propertyName: type - Address: - type: string - description: An alphanumeric string representing a blockchain address. Will - be in different formats for different chains. It is important to preserve - the exact formatting and capitalization of the address. - example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - AddressTag: - type: string - description: The secondary identifier for a blockchain address. An example of - this is the memo field on the Stellar network, which can be text, id, or hash - format. - nullable: true - example: '123456789' - TransferDestinationBlockchainLocation: - description: A destination blockchain address. + - USD + - ETH + - BTC + PaymentMethodBlockchain: type: object required: - type - chain - - address properties: type: type: string enum: - blockchain - address: - $ref: '#/components/schemas/Address' - addressTag: - $ref: '#/components/schemas/AddressTag' chain: $ref: '#/components/schemas/Chain' - TransferDestinationWalletLocation: - description: A destination wallet location. - type: object - required: - - type - - id - properties: - type: - type: string - enum: - - wallet - id: - type: string - description: The id of the wallet. - example: '12345' address: type: string - description: An alphanumeric string which indicates the wallet address used - to receive the transfer. Will only be set when the transfer source is - a blockchain address. example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: - $ref: '#/components/schemas/AddressTag' - TransferDestinationLocation: - description: A destination of funds. - oneOf: - - $ref: '#/components/schemas/TransferDestinationBlockchainLocation' - - $ref: '#/components/schemas/TransferDestinationWalletLocation' - discriminator: - propertyName: type - Money: + PaymentIntentFees: type: object required: + - type - amount - currency properties: - amount: - type: string - description: Magnitude of the amount, in units of the currency, with a `.`. - example: '3.14' - currency: + type: type: string - description: Currency code for the amount. enum: - - USD - - EUR - - BTC - - ETH - Fee: - type: object - required: - - amount - - currency - - type - properties: + - blockchainLeaseFee + - totalPaymentFees amount: + description: Magnitude of the amount, in units of the currency, with a `.`. type: string - description: Magnitude of the fee amount, in units of the currency, with - a `.`. - example: '10.00' + example: '3.14' currency: + description: Currency code. type: string - description: Currency code for the amount. enum: - USD - type: - type: string - description: Category of the fee. - enum: - - network - TransferErrorCode: - type: string - description: Indicates the failure reason of a transfer. Only present for transfers - in a `failed` state. Possible values are `insufficient_funds`, `blockchain_error` - and `transfer_denied` and `transfer_failed` - nullable: true - enum: - - transfer_failed - - transfer_denied - - blockchain_error - - insufficient_funds - Transfer: + Timeline: type: object - description: A transfer of funds. required: - - id - - source - - destination - - amount - status + - time properties: - id: - $ref: '#/components/schemas/Id' - source: - $ref: '#/components/schemas/TransferSourceLocation' - destination: - $ref: '#/components/schemas/TransferDestinationLocation' - amount: - $ref: '#/components/schemas/Money' - fees: - description: An array of fees applied to a transaction. This is only available - when there is at least one non-zero fee. - readOnly: true - type: array - items: - $ref: '#/components/schemas/Fee' - transactionHash: - description: A hash that uniquely identifies the onchain transaction. This - is only available where either source or destination are of type blockchain. - type: string - example: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' status: - description: Status of the transfer. Status `pending` indicates that the - transfer is in the process of running; `complete` indicates it finished - successfully; `failed` indicates it failed. type: string enum: + - created - pending - complete + - expired - failed - errorCode: - $ref: '#/components/schemas/TransferErrorCode' - createDate: - description: The create date of the transfer. + context: + type: string + enum: + - underpaid + - paid + - overpaid + time: + description: ISO-8601 UTC date/time format. type: string format: date-time - TransferDetailedTransfer: + PaymentIntent: type: object - description: A transfer of funds. required: - - id - - source - - destination + - idempotencyKey - amount - - status + - settlementCurrency + - paymentMethods properties: id: - $ref: '#/components/schemas/Id' - source: - $ref: '#/components/schemas/TransferSourceLocation' - destination: - $ref: '#/components/schemas/TransferDestinationLocation' + type: string + description: Unique system generated identifier for the entity. + format: uuid + example: b8627ae8-732b-4d25-b947-1df8f4007a29 amount: - $ref: '#/components/schemas/Money' + $ref: '#/components/schemas/CryptoPaymentsMoney' + amountPaid: + description: Sum of the the amount paid. + type: object + required: + - amount + - currency + properties: + amount: + description: Magnitude of the amount, in units of the currency, with + a `.`. + type: string + example: '3.14' + currency: + description: Currency code. + type: string + enum: + - USD + settlementCurrency: + description: Desired currency for the payments to settle in. + type: string + enum: + - USD + - BTC + - ETH + paymentMethods: + type: array + items: + $ref: '#/components/schemas/PaymentMethodBlockchain' fees: - description: An array of fees applied to a transaction. This is only available - when there is at least one non-zero fee. - readOnly: true type: array items: - $ref: '#/components/schemas/Fee' - transactionHash: - type: string - description: A hash that uniquely identifies the onchain transaction. This - is only available where either source or destination are of type blockchain. - example: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' - status: - type: string - description: Status of the transfer. Status `pending` indicates that the - transfer is in the process of running; `complete` indicates it finished - successfully; `failed` indicates it failed. - enum: - - failed - - pending - - complete - errorCode: - $ref: '#/components/schemas/TransferErrorCode' - riskEvaluation: - $ref: '#/components/schemas/RiskEvaluation' + $ref: '#/components/schemas/PaymentIntentFees' + paymentIds: + description: List of associated payments. + type: array + items: + type: string + format: uuid + example: 69808f36-3e5e-4f37-bf82-ca79e4d70fc1 + timeline: + description: State management timeline. + type: array + items: + $ref: '#/components/schemas/Timeline' + expiresOn: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' createDate: $ref: '#/components/schemas/UtcTimestamp' - Currency: - type: string - description: A currency associated with a balance or address. - nullable: true - enum: - - USD - - EUR - - BTC - - ETH - AddressObject: - type: object - properties: - address: - $ref: '#/components/schemas/Address' - addressTag: - $ref: '#/components/schemas/AddressTag' - currency: - $ref: '#/components/schemas/Currency' - chain: - $ref: '#/components/schemas/Chain' - GenerateAddressRequest: - type: object - required: - - idempotencyKey - - currency - - chain - properties: - idempotencyKey: - $ref: '#/components/schemas/IdempotencyKey' - currency: - $ref: '#/components/schemas/Currency' - chain: - $ref: '#/components/schemas/Chain' ExternalFiatAccountStatus: description: Status of the account. A `pending` status indicates that the linking is in-progress; `complete` indicates the account was linked successfully; @@ -3874,6 +3747,15 @@ components: description: The country code of the issuer bank. Follows the ISO 3166-1 alpha-2 standard. example: US + fundingType: + description: The funding type of the card. Possible values are `credit`, + `debit`, `prepaid`, and `unknown`. + type: string + enum: + - credit + - debit + - prepaid + - unknown fingerprint: $ref: '#/components/schemas/Fingerprint' verification: @@ -4114,6 +3996,203 @@ components: $ref: '#/components/schemas/CardExpMonth' expYear: $ref: '#/components/schemas/CardExpYear' + ApplePayTokenEcHeader: + type: object + required: + - ephemeralPublicKey + - publicKeyHash + - transactionId + properties: + applicationData: + description: Optional. Hash of the applicationData property of the original + PKPaymentRequest object. If the value of that property is null, this key + is omitted. + type: string + example: '' + ephemeralPublicKey: + description: Ephemeral public key bytes. + type: string + example: MFkwEwYHKoZIzj.../zlsw== + publicKeyHash: + description: "Hash of the X.509 encoded public key bytes of the merchant\u2019\ + s certificate." + type: string + example: tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0= + transactionId: + description: Transaction identifier, generated on the device. + type: string + example: 3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4 + ApplePayTokenRsaHeader: + type: object + required: + - wrappedKey + - publicKeyHash + - transactionId + properties: + applicationData: + description: Optional. Hash of the applicationData property of the original + PKPaymentRequest object. If the value of that property is null, this key + is omitted. + type: string + wrappedKey: + description: The symmetric key wrapped using your RSA public key. + type: string + publicKeyHash: + description: "Hash of the X.509 encoded public key bytes of the merchant\u2019\ + s certificate." + type: string + transactionId: + description: Transaction identifier, generated on the device. + type: string + ApplePayToken: + type: object + required: + - version + - data + - signature + - header + properties: + version: + description: ApplePay token version information. + type: string + enum: + - EC_v1 + - RSA_v1 + data: + description: Encrypted payment data. Base64 encoded as a string. + type: string + example: t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+...T6Ms7PhiNZpuGEE2QE= + signature: + description: Signature of the payment and header data. The signature includes + the signing certificate, its intermediate CA certificate, and information + about the signing algorithm. + type: string + example: MIAGCSqGSIb3DQEHAqCAMIACAQEx.../WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA= + header: + description: Additional version-dependent information used to decrypt and + verify the payment. + oneOf: + - $ref: '#/components/schemas/ApplePayTokenEcHeader' + - $ref: '#/components/schemas/ApplePayTokenRsaHeader' + GooglePayToken: + type: object + required: + - signature + - protocolVersion + - signedMessage + properties: + signature: + description: Verifies the message came from Google. The signature is created + using ECDSA. + type: string + protocolVersion: + description: Identifies which encryption/signing scheme created this message. + In this way, the protocol can evolve over time if needed. If it is not + set, assume ECv0. + type: string + signedMessage: + description: A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, + and tag. To simplify the signature verification process, this value is + serialized. + type: string + PaymentTokenRequest: + type: object + required: + - idempotencyKey + - type + - tokenData + properties: + idempotencyKey: + $ref: '#/components/schemas/IdempotencyKey' + type: + description: Type of the digital wallet token. + type: string + enum: + - applepay + - googlepay + tokenData: + description: The token data + oneOf: + - $ref: '#/components/schemas/ApplePayToken' + - $ref: '#/components/schemas/GooglePayToken' + TokenizedCardDetails: + type: object + required: + - expMonth + - expYear + - last4 + - bin + properties: + expMonth: + description: The card's expiration month. + type: integer + example: 1 + expYear: + description: Four digit number representing the card's expiration year. + type: integer + example: 2020 + network: + description: The network of the card. + type: string + enum: + - VISA + - MASTERCARD + - AMEX + - UNKNOWN + last4: + description: The last 4 digits of the card. + type: string + example: '0123' + bin: + description: The bank identification number (BIN), the first 6 digits of + the card. + type: string + example: '401230' + fundingType: + description: The funding type of the card. + type: string + enum: + - credit + - debit + - prepaid + - unknown + issuerCountry: + description: The country code of the issuer bank. Follows the ISO 3166-1 + alpha-2 standard. + type: string + example: US + PaymentToken: + type: object + required: + - id + - type + - expiresOn + - cardDetails + - createDate + - updateDate + properties: + id: + description: Unique system generated identifier for the digital wallet token. + type: string + format: uuid + example: gc988ed5-c189-4f70-a074-e5beb7eb8e32 + type: + description: Type of the digital wallet token. + type: string + enum: + - applepay + - googlepay + expiresOn: + description: Datetime when the digital token expires. ISO-8601. + type: string + format: date-time + example: '2022-01-18T19:20:00Z' + cardDetails: + $ref: '#/components/schemas/TokenizedCardDetails' + createDate: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' BankAddress: type: object description: The address details for the bank, as provided during bank account @@ -4750,6 +4829,27 @@ components: to the chargeback item. format: uuid example: fc988ed5-c129-4f70-a064-e5beb7eb8e32 + ChargebackStatus: + type: string + enum: + - active + - resolved + - pending + - won + - lost + - canceled + - closed + description: "Enumerated status of the chargeback. `active` means you\u2019\ + ve received a dispute and you need to submit evidence if you want to defend\ + \ against it. 'resolved' means the disputed payment had been refunded previously.\ + \ Your account has not been debited. `pending` means we have acknowledged\ + \ your evidence and forwarded it to the card issuer. `won` means you have\ + \ won the dispute and your account has been credited. `lost` means the issuing\ + \ bank has rejected your evidence and you have lost the dispute. There are\ + \ no further financial implications. `canceled` means the issuing bank has\ + \ canceled the dispute and your account has been credited. `closed` means\ + \ the time to respond to this dispute has run out. No evidence can be submitted\ + \ at this point." ChargebackCategories: type: string description: Enumerated category of the chargeback status codes based on the @@ -4813,6 +4913,7 @@ components: - id - paymentId - merchantId + - status - history - reasonCode properties: @@ -4826,6 +4927,8 @@ components: description: Reason code given by the card network for the chargeback item. type: string example: '10.4' + status: + $ref: '#/components/schemas/ChargebackStatus' category: $ref: '#/components/schemas/ChargebackCategories' history: @@ -4885,6 +4988,24 @@ components: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' + Money: + type: object + required: + - amount + - currency + properties: + amount: + type: string + description: Magnitude of the amount, in units of the currency, with a `.`. + example: '3.14' + currency: + type: string + description: Currency code for the amount. + enum: + - USD + - EUR + - BTC + - ETH Balances: type: object description: Available and unsettled balances of the merchant. diff --git a/openapi/yaml/payouts.yaml b/openapi/yaml/payouts.yaml index 53229f1..906ad17 100644 --- a/openapi/yaml/payouts.yaml +++ b/openapi/yaml/payouts.yaml @@ -1,80 +1,70 @@ openapi: 3.0.2 servers: -- url: api-sandbox.circle.com +- url: https://api-sandbox.circle.com info: - version: 1.0.3 + version: 1.1.0 title: Payouts API - description: APIs for making payouts. + description: The Circle Payouts API allows you to programmatically make fast, global + payouts to your customers, vendors, and suppliers. Use traditional methods like + bank wires and ACH, or make payouts on supported blockchains. tags: - name: Payouts -- name: On-chain payouts + description: Create and get information on wire, ACH, SEPA and address book payouts. +- name: Crypto Address Book + description: Manage blockchain addresses with metadata. - name: Wires + description: Create, get instructions, and get information on bank accounts for + wire transfers. - name: ACH + description: Link and get information on bank account for ACH payments. - name: SEPA + description: Create and get information on SEPA accounts. - name: Returns + description: Get information on returned payouts. +- name: Crypto Exchange Rates + description: Pull estimated exchange rate for crypto currencies. paths: /v1/payouts: - get: + post: security: - bearerAuth: [] - parameters: - - name: source - description: Universally unique identifier (UUID v4) for the source wallet. - Filters the results to fetch all payouts made from a source wallet. If not - provided, payouts from all wallets will be returned. - in: query - required: false - schema: - type: string - format: uuid - example: 54c1cbab-c419-450f-ad23-906fa03af7f0 - - name: type - description: Destination bank account type. Filters the results to fetch all - payouts made to a specified destination bank account type. This query parameter - can be passed multiple times to fetch results matching multiple destination - bank account types. - in: query - required: false - schema: - type: array - items: - $ref: '#/components/schemas/PayoutDestinationType' - - name: status - description: Queries items with the specified status. Matches any status if - unspecified. - in: query - required: false - schema: - type: array - items: - $ref: '#/components/schemas/PayoutStatus' - - $ref: '#/components/parameters/Destination' - - $ref: '#/components/parameters/From' - - $ref: '#/components/parameters/To' - - $ref: '#/components/parameters/PageBefore' - - $ref: '#/components/parameters/PageAfter' - - $ref: '#/components/parameters/PageSize' - summary: List all payouts - operationId: listPayouts + summary: Create a payout + description: "\nCreate a wire, ACH, SEPA or crypto payout. \n\nThe following\ + \ table includes the supported pairs of amount.currency and toAmount.currency\ + \ for address book payouts:\n\n| amount.currency | toAmount.currency |\n\ + | ---------------- | ------------ |\n| USD | USD \ + \ |\n| USD | BTC |\n| USD |\ + \ ETH |\n| USD | MTC |\n| EUR \ + \ | EUR |\n| BTC | USD \ + \ |\n| BTC | BTC |\n| ETH | USD \ + \ |\n| ETH | ETH |\n" + operationId: createPayout tags: - Payouts + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/FiatPayoutCreationRequest' + - $ref: '#/components/schemas/CryptoPayoutCreationRequest' responses: - '200': - description: Successfully retrieved a list of payouts. + '201': + description: Successfully created a payout. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListPayoutsResponse + title: CreatePayoutResponse properties: data: - type: array - items: - $ref: '#/components/schemas/Payout' + oneOf: + - $ref: '#/components/schemas/FiatPayout' + - $ref: '#/components/schemas/CryptoPayout' examples: - response: + Fiat Payout: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 @@ -86,6 +76,9 @@ paths: amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: EUR fees: amount: '3.14' currency: USD @@ -117,35 +110,138 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + Crypto Payout: + value: + data: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + sourceWalletId: '53535335' + destination: + type: address_book + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + amount: + amount: '3.14' + currency: USD + toAmount: + amount: '3.14' + currency: ETH + fees: + amount: '3.14' + currency: USD + status: pending + errorCode: transaction_denied + riskEvaluation: + decision: denied + reason: '4000' + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' - post: + get: security: - bearerAuth: [] - summary: Create a payout - operationId: createPayout + parameters: + - name: source + description: Identifier for the source wallet. Filters the fetched payout + results to only be from a specific source wallet. If not provided, payouts + from all wallets will be returned. + in: query + required: false + schema: + type: string + example: '1000565227' + - name: destination + description: Universally unique identifier (UUID v4) for the destination. + Filters the fetched payout results made to a specific destination. If not + provided, payouts to all destinations will be returned. + in: query + required: false + schema: + type: string + format: uuid + example: 54c1cbab-c419-450f-ad23-906fa03af7f0 + - name: type + description: Destination type. Filters the results to fetch all payouts made + to a specified destination type. This query parameter can be passed multiple + times to fetch results matching multiple destination types. The address_book + destination type cannot be combined with other types. + in: query + required: false + schema: + type: array + uniqueItems: true + items: + $ref: '#/components/schemas/PayoutDestinationType' + - name: status + description: Queries items with the specified status. Matches any status if + unspecified. + in: query + required: false + schema: + type: array + uniqueItems: true + items: + $ref: '#/components/schemas/PayoutStatus' + - name: sourceCurrency + description: Queries items with the specified source currency `amount.currency`. + Matches any source currency if unspecified. + in: query + required: false + schema: + type: string + enum: + - USD + - EUR + - BTC + - ETH + - MTC + - FLW + - MAN + - name: destinationCurrency + description: Queries items with the specified destination currency `toAmount.currency`. + Matches any destination currency if unspecified. + in: query + required: false + schema: + type: string + enum: + - USD + - EUR + - BTC + - ETH + - MTC + - FLW + - MAN + - $ref: '#/components/parameters/Chain' + - $ref: '#/components/parameters/From' + - $ref: '#/components/parameters/To' + - $ref: '#/components/parameters/PageBefore' + - $ref: '#/components/parameters/PageAfter' + - $ref: '#/components/parameters/PageSize' + summary: List all payouts + operationId: listPayouts tags: - Payouts - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PayoutCreationRequest' responses: - '201': - description: Successfully created a payout. + '200': + description: Successfully retrieved a list of payouts. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: CreatePayoutResponse + title: ListPayoutsResponse properties: data: - $ref: '#/components/schemas/Payout' + type: array + items: + anyOf: + - $ref: '#/components/schemas/FiatPayout' + - $ref: '#/components/schemas/CryptoPayout' examples: - response: + Fiat Payout: value: data: id: b8627ae8-732b-4d25-b947-1df8f4007a29 @@ -157,6 +253,9 @@ paths: amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: EUR fees: amount: '3.14' currency: USD @@ -188,8 +287,30 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' - '400': - $ref: '#/components/responses/BadRequest' + Crypto Payout: + value: + data: + - id: b8627ae8-732b-4d25-b947-1df8f4007a29 + sourceWalletId: '53535335' + destination: + type: address_book + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + amount: + amount: '3.14' + currency: USD + toAmount: + amount: '3.14' + currency: ETH + fees: + amount: '3.14' + currency: USD + status: pending + errorCode: transaction_denied + riskEvaluation: + decision: denied + reason: '4000' + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' '401': $ref: '#/components/responses/NotAuthorized' /v1/payouts/{id}: @@ -214,9 +335,11 @@ paths: title: GetPayoutResponse properties: data: - $ref: '#/components/schemas/DetailedPayout' + oneOf: + - $ref: '#/components/schemas/FiatDetailedPayout' + - $ref: '#/components/schemas/CryptoPayout' examples: - response: + Fiat Payout: value: data: id: b8627ae8-732b-4d25-b947-1df8f4007a29 @@ -228,6 +351,9 @@ paths: amount: amount: '3.14' currency: USD + toAmount: + amount: '3.14' + currency: EUR fees: amount: '3.14' currency: USD @@ -260,296 +386,266 @@ paths: updateDate: '2020-04-10T02:13:30.000Z' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' + Crypto Payout: + value: + data: + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + sourceWalletId: '53535335' + destination: + type: address_book + id: b8627ae8-732b-4d25-b947-1df8f4007a29 + amount: + amount: '3.14' + currency: USD + toAmount: + amount: '3.14' + currency: ETH + fees: + amount: '3.14' + currency: USD + status: pending + errorCode: transaction_denied + riskEvaluation: + decision: denied + reason: '4000' + createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' '401': $ref: '#/components/responses/NotAuthorized' '404': $ref: '#/components/responses/NotFound' - /v1/transfers: + /v1/addressBook/recipients: post: security: - bearerAuth: [] - summary: Create a transfer - description: A transfer can be made from an existing funded wallet to a blockchain - address or another wallet. - operationId: createTransfer + summary: Create a recipient + operationId: createAddressBookRecipient tags: - - On-chain payouts + - Crypto Address Book requestBody: content: application/json: schema: - $ref: '#/components/schemas/TransferCreationRequest' - examples: - request: - value: - idempotencyKey: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 - source: - type: wallet - id: '12345' - destination: - type: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH - amount: - amount: '3.14' - currency: USD - travel rule: - value: - 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: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH - amount: - amount: '3000.00' - currency: USD + $ref: '#/components/schemas/AddressBookRecipientRequest' responses: '201': + description: Successfully created an address book recipient. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' - description: Successfully created a transfer. content: application/json: schema: - title: CreateTransferResponse + title: CreateAddressBookRecipientResponse properties: data: - $ref: '#/components/schemas/Transfer' + $ref: '#/components/schemas/AddressBookRecipient' examples: response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - source: - type: wallet - id: '12345' - destination: - type: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH - amount: - amount: '3.14' - currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' - status: pending - createDate: '2020-04-10T02:13:30.000Z' - travel rule: - value: - data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - 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: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH - amount: - amount: '3000.00' - currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' + id: 8755d0ea-14f9-4259-b092-de23c14b6568 + chain: ETH + address: '0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle status: pending - createDate: '2020-04-10T02:13:30.000Z' + createDate: '2022-07-21T20:13:35.578678Z' + updateDate: '2022-07-21T20:19:24.859052Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' get: security: - bearerAuth: [] + summary: List all recipients + operationId: listAddressBookRecipients + tags: + - Crypto Address Book parameters: - - name: walletId - description: Unique identifier for the source or destination wallet of transfers, - if any. May not be used in conjunction with destinationWalletId or sourceWalletId. - Useful for fetching all transfers related to a wallet. + - name: address + description: Filters results to fetch only address book recipients with the + provided address. in: query required: false schema: type: string - example: '12345' - - name: sourceWalletId - description: Unique identifier for the source wallet of transfers, if any. + - name: chain + description: Filters results to fetch only address book recipients with the + provided chain. in: query required: false schema: type: string - example: '12345' - - name: destinationWalletId - description: Unique identifier for the destination wallet of transfers, if - any. + - name: email + description: Filters results to fetch only address book recipients that have + the provided email in their metadata. in: query required: false schema: type: string - example: '12345' - - $ref: '#/components/parameters/ReturnIdentities' + - name: status + description: Filters results to fetch only address book recipients that have + the provided status. + in: query + required: false + schema: + type: string + enum: + - pending + - inactive + - active + - denied - $ref: '#/components/parameters/From' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/PageBefore' - $ref: '#/components/parameters/PageAfter' - $ref: '#/components/parameters/PageSize' - summary: List all transfers - description: Searches for transfers involving the provided wallets. If no wallet - ids are provided, searches all wallets associated with your Circle API account. - If the date parameters are omitted, returns the most recent transfers. This - endpoint returns up to 50 transfers in descending chronological order or pageSize, - if provided. - operationId: listTransfers - tags: - - On-chain payouts responses: '200': - description: Successfully retrieved a list of transfers. + description: Successfully retrieved a list of address book recipients. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: - title: ListTransfersResponse + title: ListAddressBookRecipientsResponse properties: data: type: array items: - $ref: '#/components/schemas/Transfer' + $ref: '#/components/schemas/AddressBookRecipient' examples: response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - source: - type: wallet - id: '12345' - destination: - type: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: '123456789' - chain: ALGO - amount: - amount: '3.14' - currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' - status: pending - createDate: '2020-04-10T02:13:30.000Z' - travel rule: - value: - data: - - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - 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: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: '123456789' - chain: ALGO - amount: - amount: '3000.00' - currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' + chain: ALGO + address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + addressTag: '123456789' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle status: pending createDate: '2020-04-10T02:13:30.000Z' + updateDate: '2020-04-10T02:13:30.000Z' '401': $ref: '#/components/responses/NotAuthorized' - /v1/transfers/{id}: + /v1/addressBook/recipients/{id}: get: parameters: - $ref: '#/components/parameters/IdPath' - - $ref: '#/components/parameters/ReturnIdentities' security: - bearerAuth: [] - summary: Get a transfer - operationId: getTransfer + summary: Get a recipient + operationId: getAddressBookRecipient tags: - - On-chain payouts + - Crypto Address Book responses: '200': + description: Successfully retrieved an address book recipient. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' - description: Successfully retrieved a transfer. content: application/json: schema: - title: GetTransferResponse + title: GetAddressBookRecipientResponse properties: data: - $ref: '#/components/schemas/TransferDetailedTransfer' + $ref: '#/components/schemas/AddressBookRecipient' examples: response: value: data: id: b8627ae8-732b-4d25-b947-1df8f4007a29 - source: - type: wallet - id: '12345' - destination: - type: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH - amount: - amount: '3.14' - currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' + chain: ALGO + address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + addressTag: '123456789' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle status: pending createDate: '2020-04-10T02:13:30.000Z' - travel rule: + updateDate: '2020-04-10T02:13:30.000Z' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + patch: + parameters: + - $ref: '#/components/parameters/IdPath' + security: + - bearerAuth: [] + summary: Modify a recipient + operationId: modifyAddressBookRecipient + tags: + - Crypto Address Book + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddressBookRecipientModifyRequest' + responses: + '200': + description: Successfully updated the address book recipient. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: ModifyAddressBookRecipientResponse + properties: + data: + $ref: '#/components/schemas/AddressBookRecipient' + examples: + response: value: data: - id: b8627ae8-732b-4d25-b947-1df8f4007a29 - 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: blockchain - address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - chain: ETH - amount: - amount: '3000.00' - currency: USD - transactionHash: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' + id: 8755d0ea-14f9-4259-b092-de23c14b6568 + chain: ETH + address: '0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3' + metadata: + nickname: sample nickname + email: satoshi@circle.com + bns: sample.circle status: pending - createDate: '2020-04-10T02:13:30.000Z' + createDate: '2022-07-21T20:13:35.578678Z' + updateDate: '2022-07-21T20:19:24.859052Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' + delete: + parameters: + - $ref: '#/components/parameters/IdPath' + security: + - bearerAuth: [] + summary: Delete a recipient + operationId: deleteAddressBookRecipient + tags: + - Crypto Address Book + responses: + '200': + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + description: Successfully removed the address book recipient. + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' + '404': + $ref: '#/components/responses/NotFound' /v1/banks/wires: post: security: @@ -808,7 +904,7 @@ paths: content: application/json: schema: - title: CreateAchAccountResponse + title: CreateMockAchAccountResponse properties: data: $ref: '#/components/schemas/MockAchAccountResponse' @@ -981,6 +1077,53 @@ paths: $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' + /v1/exchange/rates/{trading-pair}: + get: + security: + - bearerAuth: [] + summary: Get a exchange rate + description: Fetch the current rates for the specified trading pair. The trading + pair is defined by a base currency followed by a quote currency. The response + contains buy and sell rates denominated in the quote currency. **Exchange + rate is an estimate only and is subject to change by the time you submit the + actual request.** + operationId: getExchangeRates + tags: + - Crypto Exchange Rates + parameters: + - name: trading-pair + in: path + required: true + schema: + type: string + enum: + - BTC-USD + - ETH-USD + - FLOW-USD + responses: + '200': + description: Successfully retrieved rates. + headers: + X-Request-Id: + $ref: '#/components/headers/XRequestId' + content: + application/json: + schema: + title: GetExchangeRatesResponse + properties: + data: + $ref: '#/components/schemas/Rate' + examples: + response: + value: + data: + buy: '46317.59000' + sell: '45400.41000' + createDate: '2020-04-10T02:13:30.000Z' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/NotAuthorized' components: securitySchemes: bearerAuth: @@ -989,11 +1132,12 @@ components: schemas: PayoutDestinationType: type: string - description: The destination bank account type. + description: The destination type. enum: - wire - ach - sepa + - address_book PayoutStatus: type: string description: Status of the payout. Status `pending` indicates that the payout @@ -1008,22 +1152,28 @@ components: description: Unique system generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 - BankDestination: + FiatPayoutDestinationType: + type: string + description: The destination type. + enum: + - wire + - ach + - sepa + FiatPayoutDestination: type: object - description: The destination bank account. + description: The destination. required: - type - id properties: type: - $ref: '#/components/schemas/PayoutDestinationType' + $ref: '#/components/schemas/FiatPayoutDestinationType' id: $ref: '#/components/schemas/Id' name: type: string description: Bank name plus last four digits of the bank account number or IBAN. - readOnly: true example: COMMERZBANK AG ****3000 FiatMoneyUsd: type: object @@ -1040,6 +1190,27 @@ components: type: string enum: - USD + PayoutMoney: + type: object + required: + - amount + - currency + properties: + amount: + type: string + description: Magnitude of the amount, in units of the currency, with a `.`. + example: '3.14' + currency: + type: string + description: Currency code for the amount. + enum: + - USD + - EUR + - BTC + - ETH + - MTC + - FLW + - MAN PayoutErrorCode: type: string nullable: true @@ -1127,7 +1298,7 @@ components: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' - Payout: + FiatPayout: type: object properties: id: @@ -1137,9 +1308,11 @@ components: description: The identifier of the source wallet used to fund a payout. example: '53535335' destination: - $ref: '#/components/schemas/BankDestination' + $ref: '#/components/schemas/FiatPayoutDestination' amount: $ref: '#/components/schemas/FiatMoneyUsd' + toAmount: + $ref: '#/components/schemas/PayoutMoney' fees: $ref: '#/components/schemas/FiatMoneyUsd' status: @@ -1160,6 +1333,49 @@ components: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' + CryptoPayoutDestinationType: + type: string + description: The destination type. + enum: + - address_book + CryptoPayoutDestination: + type: object + description: The destination. + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/CryptoPayoutDestinationType' + id: + $ref: '#/components/schemas/Id' + CryptoPayout: + type: object + properties: + id: + $ref: '#/components/schemas/Id' + sourceWalletId: + type: string + description: The identifier of the source wallet used to fund a payout. + example: '53535335' + destination: + $ref: '#/components/schemas/CryptoPayoutDestination' + amount: + $ref: '#/components/schemas/PayoutMoney' + toAmount: + $ref: '#/components/schemas/PayoutMoney' + fees: + $ref: '#/components/schemas/PayoutMoney' + status: + $ref: '#/components/schemas/PayoutStatus' + errorCode: + $ref: '#/components/schemas/PayoutErrorCode' + riskEvaluation: + $ref: '#/components/schemas/RiskEvaluation' + createDate: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' IdempotencyKey: type: string description: Universally unique identifier (UUID v4) idempotency key. This key @@ -1193,7 +1409,7 @@ components: properties: beneficiaryEmail: $ref: '#/components/schemas/Email' - PayoutCreationRequest: + FiatPayoutCreationRequest: type: object required: - idempotencyKey @@ -1206,61 +1422,20 @@ components: source: $ref: '#/components/schemas/WalletLocation' destination: - $ref: '#/components/schemas/BankDestination' + type: object + description: The destination. + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/FiatPayoutDestinationType' + id: + $ref: '#/components/schemas/Id' amount: $ref: '#/components/schemas/FiatMoneyUsd' metadata: $ref: '#/components/schemas/MetadataPayout' - ExternalRef: - type: string - description: "External network identifier which will be present once provided\ - \ from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability\ - \ Data (IMAD/OMAD)**: unique number given to each FedWire payment when using\ - \ the Federal Reserve Bank Service which can be used to investigate and track\ - \ wire transfers.\n" - example: YYYYMMDDXXXXXXXX012345 - DetailedPayout: - type: object - properties: - id: - $ref: '#/components/schemas/Id' - sourceWalletId: - description: The identifier of the source wallet used to fund a payout. - type: string - example: '53535335' - destination: - $ref: '#/components/schemas/BankDestination' - amount: - $ref: '#/components/schemas/FiatMoneyUsd' - fees: - $ref: '#/components/schemas/FiatMoneyUsd' - status: - description: Status of the payout. Status `pending` indicates that the payout - is in process; `complete` indicates it finished successfully; `failed` - indicates it failed. - type: string - enum: - - pending - - complete - - failed - trackingRef: - description: A payout tracking reference. Will be present once known. - nullable: true - example: CIR-6ESOQANEP3NAO - externalRef: - $ref: '#/components/schemas/ExternalRef' - errorCode: - $ref: '#/components/schemas/PayoutErrorCode' - riskEvaluation: - $ref: '#/components/schemas/RiskEvaluation' - adjustments: - $ref: '#/components/schemas/FinalAdjustments' - return: - $ref: '#/components/schemas/UnwithdrawalObject' - createDate: - $ref: '#/components/schemas/UtcTimestamp' - updateDate: - $ref: '#/components/schemas/UtcTimestamp' IdentityAddress: type: object required: @@ -1305,128 +1480,40 @@ components: example: US Identity: type: object - description: "The identity of the originator. Identities are required when:\n\ - \ * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n\ - \ * `amount.amount` >= $3,000 in value\n" - required: - - type - - name - - addresses - properties: - type: - type: string - description: 'The type of identity for the originator. - - * `individual` - A uniquely distinguishable individual. - - * `business` - Any entity other than a natural person that can establish - a permanent customer relationship with an affected entity or otherwise - own property. This can include companies, foundations, anstalt, partnerships, - associations and other relevantly similar entities. - - ' - enum: - - individual - - business - name: - type: string - description: Full name of the identity. - example: Satoshi Nakamoto - maxLength: 1024 - addresses: - type: array - items: - $ref: '#/components/schemas/IdentityAddress' - TransferSourceWalletLocation: - description: A source wallet location. - type: object - required: - - type - - id - properties: - type: - type: string - enum: - - wallet - id: - type: string - description: The id of the wallet. - example: '12345' - identities: - type: array - items: - $ref: '#/components/schemas/Identity' - Chain: - type: string - description: A blockchain that a given currency is available on. - enum: - - ALGO - - AVAX - - BTC - - ETH - - FLOW - - HBAR - - MATIC - - SOL - - TRX - - XLM - TransferSourceBlockchainLocation: - description: A source blockchain address. - type: object + description: "The identity of the originator. Identities are required when:\n\ + \ * `destination.type: \"blockchain\"`\n * `destination.chain: \"ETH\"`\n\ + \ * `amount.amount` >= $3,000 in value\n" required: - type - - chain + - name + - addresses properties: type: type: string + description: 'The type of identity for the originator. + + * `individual` - A uniquely distinguishable individual. + + * `business` - Any entity other than a natural person that can establish + a permanent customer relationship with an affected entity or otherwise + own property. This can include companies, foundations, anstalt, partnerships, + associations and other relevantly similar entities. + + ' enum: - - blockchain - chain: - $ref: '#/components/schemas/Chain' - identities: + - individual + - business + name: + type: string + description: Full name of the identity. + example: Satoshi Nakamoto + maxLength: 1024 + addresses: type: array items: - $ref: '#/components/schemas/Identity' - TransferSourceLocation: - description: A source of funds. - oneOf: - - $ref: '#/components/schemas/TransferSourceWalletLocation' - - $ref: '#/components/schemas/TransferSourceBlockchainLocation' - discriminator: - propertyName: type - Address: - type: string - description: An alphanumeric string representing a blockchain address. Will - be in different formats for different chains. It is important to preserve - the exact formatting and capitalization of the address. - example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - AddressTag: - type: string - description: The secondary identifier for a blockchain address. An example of - this is the memo field on the Stellar network, which can be text, id, or hash - format. - nullable: true - example: '123456789' - TransferDestinationBlockchainLocation: - description: A destination blockchain address. - type: object - required: - - type - - chain - - address - properties: - type: - type: string - enum: - - blockchain - address: - $ref: '#/components/schemas/Address' - addressTag: - $ref: '#/components/schemas/AddressTag' - chain: - $ref: '#/components/schemas/Chain' - TransferDestinationWalletLocation: - description: A destination wallet location. + $ref: '#/components/schemas/IdentityAddress' + TransferSourceWalletLocation: + description: A source wallet location. type: object required: - type @@ -1440,21 +1527,10 @@ components: type: string description: The id of the wallet. example: '12345' - address: - type: string - description: An alphanumeric string which indicates the wallet address used - to receive the transfer. Will only be set when the transfer source is - a blockchain address. - example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' - addressTag: - $ref: '#/components/schemas/AddressTag' - TransferDestinationLocation: - description: A destination of funds. - oneOf: - - $ref: '#/components/schemas/TransferDestinationBlockchainLocation' - - $ref: '#/components/schemas/TransferDestinationWalletLocation' - discriminator: - propertyName: type + identities: + type: array + items: + $ref: '#/components/schemas/Identity' Money: type: object required: @@ -1473,184 +1549,181 @@ components: - EUR - BTC - ETH - Fee: + ToAmount: type: object required: - - amount - currency - - type properties: - amount: - type: string - description: Magnitude of the fee amount, in units of the currency, with - a `.`. - example: '10.00' currency: type: string description: Currency code for the amount. enum: - USD - type: - type: string - description: Category of the fee. - enum: - - network - TransferErrorCode: - type: string - description: Indicates the failure reason of a transfer. Only present for transfers - in a `failed` state. Possible values are `insufficient_funds`, `blockchain_error` - and `transfer_denied` and `transfer_failed` - nullable: true - enum: - - transfer_failed - - transfer_denied - - blockchain_error - - insufficient_funds - Transfer: + - EUR + - BTC + - ETH + - MTC + CryptoPayoutCreationRequest: type: object - description: A transfer of funds. required: - - id - - source + - idempotencyKey - destination - amount - - status properties: - id: - $ref: '#/components/schemas/Id' + idempotencyKey: + $ref: '#/components/schemas/IdempotencyKey' source: - $ref: '#/components/schemas/TransferSourceLocation' + $ref: '#/components/schemas/TransferSourceWalletLocation' destination: - $ref: '#/components/schemas/TransferDestinationLocation' + $ref: '#/components/schemas/CryptoPayoutDestination' amount: $ref: '#/components/schemas/Money' - fees: - description: An array of fees applied to a transaction. This is only available - when there is at least one non-zero fee. - readOnly: true - type: array - items: - $ref: '#/components/schemas/Fee' - transactionHash: - description: A hash that uniquely identifies the onchain transaction. This - is only available where either source or destination are of type blockchain. + toAmount: + $ref: '#/components/schemas/ToAmount' + ExternalRef: + type: string + description: "External network identifier which will be present once provided\ + \ from the applicable network. \n\nExamples:\n* **Input/Output Message Accountability\ + \ Data (IMAD/OMAD)**: unique number given to each FedWire payment when using\ + \ the Federal Reserve Bank Service which can be used to investigate and track\ + \ wire transfers.\n" + example: YYYYMMDDXXXXXXXX012345 + FiatDetailedPayout: + type: object + properties: + id: + $ref: '#/components/schemas/Id' + sourceWalletId: + description: The identifier of the source wallet used to fund a payout. type: string - example: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' + example: '53535335' + destination: + $ref: '#/components/schemas/FiatPayoutDestination' + amount: + $ref: '#/components/schemas/FiatMoneyUsd' + toAmount: + $ref: '#/components/schemas/PayoutMoney' + fees: + $ref: '#/components/schemas/FiatMoneyUsd' status: - description: Status of the transfer. Status `pending` indicates that the - transfer is in the process of running; `complete` indicates it finished - successfully; `failed` indicates it failed. + description: Status of the payout. Status `pending` indicates that the payout + is in process; `complete` indicates it finished successfully; `failed` + indicates it failed. type: string enum: - pending - complete - failed + trackingRef: + description: A payout tracking reference. Will be present once known. + nullable: true + example: CIR-6ESOQANEP3NAO + externalRef: + $ref: '#/components/schemas/ExternalRef' errorCode: - $ref: '#/components/schemas/TransferErrorCode' + $ref: '#/components/schemas/PayoutErrorCode' + riskEvaluation: + $ref: '#/components/schemas/RiskEvaluation' + adjustments: + $ref: '#/components/schemas/FinalAdjustments' + return: + $ref: '#/components/schemas/UnwithdrawalObject' createDate: - description: The create date of the transfer. - type: string - format: date-time - TransferRequestSourceWalletLocation: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' + Chain: + type: string + description: A blockchain that a given currency is available on. + enum: + - ALGO + - AVAX + - BTC + - ETH + - FLOW + - HBAR + - MATIC + - SOL + - TRX + - XLM + Address: + type: string + description: An alphanumeric string representing a blockchain address. Will + be in different formats for different chains. It is important to preserve + the exact formatting and capitalization of the address. + example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + AddressTag: + type: string + description: The secondary identifier for a blockchain address. An example of + this is the memo field on the Stellar network, which can be text, id, or hash + format. + nullable: true + example: '123456789' + AddressBookRecipientMetadata: type: object - required: - - type - - id properties: - type: + nickname: type: string - enum: - - wallet - id: + description: Nickname related to the address. + example: sample nickname + email: + $ref: '#/components/schemas/Email' + bns: type: string - description: The id of the wallet. - example: '12345' - identities: - type: array - items: - $ref: '#/components/schemas/Identity' - TransferRequestBlockchainLocation: + description: Blockchain Name Service (e.g. ENS) domain for the address. + example: sample.circle + AddressBookRecipient: type: object required: - - type - - address - chain + - address + - metadata properties: - type: - type: string - enum: - - blockchain + id: + $ref: '#/components/schemas/Id' + chain: + $ref: '#/components/schemas/Chain' address: - type: string - description: The blockchain address. - example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' + $ref: '#/components/schemas/Address' addressTag: $ref: '#/components/schemas/AddressTag' - chain: - $ref: '#/components/schemas/Chain' - TransferCreationRequest: + metadata: + $ref: '#/components/schemas/AddressBookRecipientMetadata' + status: + type: string + description: Status of the address book recipient. + enum: + - pending + - inactive + - active + - denied + createDate: + $ref: '#/components/schemas/UtcTimestamp' + updateDate: + $ref: '#/components/schemas/UtcTimestamp' + AddressBookRecipientRequest: type: object required: - idempotencyKey - - source - - destination - - amount + - chain + - address + - metadata properties: idempotencyKey: $ref: '#/components/schemas/IdempotencyKey' - source: - $ref: '#/components/schemas/TransferRequestSourceWalletLocation' - destination: - oneOf: - - $ref: '#/components/schemas/TransferRequestBlockchainLocation' - - $ref: '#/components/schemas/WalletLocation' - amount: - $ref: '#/components/schemas/Money' - TransferDetailedTransfer: + chain: + $ref: '#/components/schemas/Chain' + address: + $ref: '#/components/schemas/Address' + addressTag: + $ref: '#/components/schemas/AddressTag' + metadata: + $ref: '#/components/schemas/AddressBookRecipientMetadata' + AddressBookRecipientModifyRequest: type: object - description: A transfer of funds. - required: - - id - - source - - destination - - amount - - status properties: - id: - $ref: '#/components/schemas/Id' - source: - $ref: '#/components/schemas/TransferSourceLocation' - destination: - $ref: '#/components/schemas/TransferDestinationLocation' - amount: - $ref: '#/components/schemas/Money' - fees: - description: An array of fees applied to a transaction. This is only available - when there is at least one non-zero fee. - readOnly: true - type: array - items: - $ref: '#/components/schemas/Fee' - transactionHash: - type: string - description: A hash that uniquely identifies the onchain transaction. This - is only available where either source or destination are of type blockchain. - example: '0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63' - status: - type: string - description: Status of the transfer. Status `pending` indicates that the - transfer is in the process of running; `complete` indicates it finished - successfully; `failed` indicates it failed. - enum: - - failed - - pending - - complete - errorCode: - $ref: '#/components/schemas/TransferErrorCode' - riskEvaluation: - $ref: '#/components/schemas/RiskEvaluation' - createDate: - $ref: '#/components/schemas/UtcTimestamp' + metadata: + $ref: '#/components/schemas/AddressBookRecipientMetadata' BillingDetails: type: object required: @@ -2237,18 +2310,44 @@ components: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' + Rate: + type: object + required: + - buy + - sell + - createDate + properties: + buy: + type: string + description: The buy rate denominated in the quote currency of the trading + pair. + example: '46317.59000' + sell: + type: string + description: The sell rate denominated in the quote currency of the trading + pair. + example: '45400.41000' + createDate: + $ref: '#/components/schemas/UtcTimestamp' parameters: - Destination: - name: destination - description: Universally unique identifier (UUID v4) for the destination bank - account. Filters the results to fetch all payouts made to a destination bank - account. + Chain: + name: chain + description: Queries items with the specified chain. Matches any chain if unspecified in: query required: false schema: type: string - format: uuid - example: e3d0a838-d732-49d0-bf44-73a668e38973 + enum: + - ALGO + - AVAX + - BTC + - ETH + - FLOW + - HBAR + - MATIC + - SOL + - TRX + - XLM From: name: from description: Queries items created since the specified date-time (inclusive). @@ -2346,17 +2445,6 @@ components: type: string format: uuid example: b3d9d2d5-4c12-4946-a09d-953e82fae2b0 - ReturnIdentities: - name: returnIdentities - description: Specify if you would like to see identities in the response. Restricts - maximum returned items to 5. By default returnIdentities is false, resulting - in the response not returning `data.source.identities`. - in: query - required: false - schema: - type: boolean - example: 'true' - default: false headers: XRequestId: description: Universally unique identifier (UUID v4) for the request. Helpful