Skip to Content

Testing URL: https://api-sandbox.koywe.com/graphql 

This URL runs an Apollo explorer instance, in case you want to test directly from your browser.

Contact us at hola@koywe.com to get your Credentials or to schedule a personalized tour around the platoform.

Testing: Our testing API works on the different testnets of major blockchains. We have a limited token stock, so we ask your help in not using them all or returning the tokens once the testing is done.

Queries and Mutations

To send requests to the GraphQL API, you always have to send a POST request to the base URL, including the query and any variable as a JSON object. An example to authenticate using CURL (Authorization header included for illustrative purposes):

curl --request POST \ --header 'content-type: application/json' \ --header 'Authorization: Bearer JWTTOKEN' \ --url 'https://api-sandbox.koywe.com/graphql' \ --data '{"query":"mutation authenticate($input: AuthInput!) {\n authenticate(input: $input) {\n token\n }\n}","variables":{"input":{"clientId":"63631a561f41f8fd18f8c3e0","secret":"supersecretstringFTW"}}}'

In the following examples, we will only write down the JSON object.

Authentication

Returns a Bearer Token that lasts for 24 hours.

Require: clientId, secret

Optional: email. This field associates the transactions and requests to a specific user account.

mutation Authenticate($input: AuthInput!) { authenticate(input: $input) { token } } "variables" : { "input": { "clientId": "63631a561f41f8fd18f8c3e0", "secret": "secretpassword", "email": "email@domain.com" # optional } }

The next two services allows in a directly way the validation of a final user. The first service sends a code to an email specified by the user’s input. This code must be provided as an input to the second service, where the user will be validated and session data will be returned.

Validation of session

Sends a 6-digit code to the email specified.

mutation validateAccount($input: ValidateAccountInput!) { validateAccount(input: $input) { _id } } "variables" : { "input": { "email": "email@domain.com", "clientId": "f87aad3as90fe5489bb5099f" } }
Code's validation

Value of code must be retrieved from the email sent by the previous service.

mutation validateCode($input: ValidateCodeInput!) { validateCode(input: $input) { token isIdentify needVerificate identity firstOp } } "variables" : { "input": { "clientId": "40401a5615d9d8fd18f8a0b4", "code": "940577", "email": "example@domain.com" } }
Pairs

Returns supported currency-tokens pairs.

Optional: symbol: Currency symbol to filter pairs. clientId.

query GetCurrencyTokensV2($input: GetCurrenciesInput!) { GetCurrencyTokensV2(input: $input) { _id name symbol decimals clientId logo locate limits { min max } tokens { _id name symbol decimals logo } } } "variables": { "input": { "symbol": null, "clientId": null } }

Returns supported token-currencies pairs.

Optional: symbol. El símbolo del cripto a elección. clientId

query GetTokenCurrencies($input: GetCurrenciesInput!) { GetTokenCurrencies(input: $input) { _id name symbol decimals logo currencies { _id name symbol decimals locale logo limits { min max } } } } "variables": { "input": { "symbol": null, "clientId": null } }
Payment Methods

Returns a list of available payment methods with each method’s fees and details for a specific currency.

Require: symbol. currencyId.

Optional: clientId. Payment method list could vary according to this parameter.

query GetPaymentProviderList($input: GetPaymentProviderListInput!) { getPaymentProviderList(input: $input) { _id name fee image description details } } "variables": { "input": { "symbol": "COP" "clientId": "f87aad3as90fe5489bb5099f" "currencyId": "489bb507aad3as90fe0f" } }

Rules for Bank Transfer Payments WIRE: For payments made through bank transfer, the following rules have been established:

  • Users are allowed to have only one active order per client if they use bank transfer as their payment method. This implies that if a user creates a new order via bank transfer, any previous orders will be canceled, and only the latest order will remain active.
  • If a user makes a payment through bank transfer, and the balance is not equal to the order amount, the system will automatically adjust the order. This adjustment is necessary for both payments that are less than the order amount and orders that exceed the specified amount.
Payout Providers
This endpoint is deprecated and will be removed in a future version.

Returns a list of available payout providers with each method’s fees and details for a specific currency.

Require: symbol. currencyId.

Optional: clientId. Payment method list could vary according to this parameter.

query GetPayoutProviderList($input: GetPayoutProviderListInput!) { getPayoutProviderList(input: $input) { _id name fee image description details } } "variables": { "input": { "symbol": "COP" "clientId": "f87aad3as90fe5489bb5099f" "currencyId": "489bb507aad3as90fe0f" } }
Quote services

Get Quote

Returns a quote associated with a quoteId.

query getQuote($quoteId: String!) { getQuote(quoteId: $quoteId) { amountIn amountOut co2 exchangeRate symbolIn symbolOut paymentMethodId koyweFee networkFee validFor validUntil } } "variables": { "quoteId": "63c59396a38c6506a620162f" #Created when calling mutation quote }

Create Quote

Requires: amountIn o amountOut, one or the other. symbolIn, symbolOut Optional: paymentMethodId, clientId

mutation quote($input: QuoteInput!) { quote(input: $input) { quoteId amountIn amountOut co2 exchangeRate symbolIn symbolOut paymentMethodId koyweFee networkFee validFor validUntil } } "variables": { "input": { "amountIn": 3716338, "amountOut": 3.3, "clientId": "cse7fj283rkn2x6v7rr", "symbolIn": "CLP", "symbolOut": "ETH", "paymentMethodId": null, # This value corresponds to the _id value returned after calling GetPaymentProviderList "executable": false #set false by default. If value is set true, we store it and return a UUID. } }

In all the previous queries, the clientId parameter will be ignored if there’s a JWT Bearer Token in the headers.

Authenticated Queries

All the following queries require a Bearer Token in the headers:

Authorization: Bearer [token]
Accounts

These user services include: the creation of new user profiles, the ability to update user information, the possibility of consulting user details, and a validation function that checks if the user has provided enough personal data to be able to operate.

See Considerations

Check account

It verifies the user account information and determines if it is possible to perform any operation. If any user data is missing, it could be added through the user update service detailed further below.

query CheckAccount($input: InputEmailAccountDto!) { checkAccount(input: $input) { canOperate errors { field message } accountStatus nextVerificationDate } } "variables" : { "input": { "email": "email@domain.com" } }

Get account

Returns the registered information of the user.

query GetAccountProfile($input: InputEmailAccountDto!) { getAccountProfile(input: $input) { document { documentNumber documentType country isCompany others { documentNumber documentType country } } address { addressStreet addressCountry addressZipCode addressNeighborhood addressCity addressState } personalInfo { names firstLastname secondLastname nationality gender dob phoneNumber activity } email } } "variables" : { "input": { "email": "email@domain.com" } }

Create account

Creates a new user account.

mutation CreateAccount($input: InputCreateAccountDto!) { createAccount(input: $input) { document { documentNumber documentType country isCompany others { documentNumber documentType country } } address { addressStreet addressCountry addressNeighborhood addressCity addressState addressZipCode } personalInfo { names firstLastname secondLastname nationality gender dob phoneNumber activity } email } } "variables" : { "input": { "email": "email@domain.com", "document": { "documentNumber": "", "documentType": "", "country": "", "isCompany": false, "others": [ { "documentNumber": "", "documentType": "", "country": "" } ] }, "address": { "addressStreet": "", "addressCountry": "", "addressZipCode": "", "addressCity": "", "addressState": "" }, "personalInfo": { "names": "", "firstLastname": "", "secondLastname": "", "nationality": "", "dob": "", "gender": "", "phoneNumber": "", "activity": "" } } }

Update account

Updates user data. If an updated email is present, the API validates whether it is a valid email and ensures that another account with that email does not already exist.

If an updated document number or type is present, the API validates that it has a valid format, does not exist on another account, has no executed orders, and initiates an asynchronous validation for mismatching personal data.

The results of the asynchronous validation will be sent to the configured callback. You can find more information in the webhooks section.

mutation UpdateAccount($input: InputUpdateAccountDto!) { updateAccount(input: $input) { document { documentNumber documentType country isCompany others { documentNumber documentType country } } address { addressStreet addressCountry addressNeighborhood addressCity addressState addressZipCode } personalInfo { names firstLastname secondLastname nationality gender dob phoneNumber activity } email, resultUpdateDocumentNumber } } "variables" : { "input": { "email": "email@domain.com" "document": { "documentNumber": "", "documentType": "", "country": "", "others": [ { "documentNumber": "", "documentType": "", "country": "" } ] }, "address": { "addressStreet": "", "addressCountry": "", "addressZipCode": "", "addressCity": "", "addressState": "", "addressNeighborhood": "" }, "personalInfo": { "names": "", "firstLastname": "", "secondLastname": "", "nationality": "", "dob": "", "activity": "", "gender": "", "phoneNumber": "" }, "updateDocumentNumber", "updateDocumentType", "updateEmail" } }

Get Account By Filter

Returns the registered document information of a user based on their identification details.

Authentication Required: Include Bearer Token in headers:

Authorization: Bearer [token]

Required Fields:

  • documentNumber: The identification number of the user
  • documentType: The type of identification document (e.g., DNI, RUT, CPF)
  • country: The ISO 3166-1 alpha-3 country code (e.g., CHL, PER, COL)
query GetAccountByFilter($input: InputAccountFilterDto!) { getAccountByFilter(input: $input) { document { documentNumber # Unique identifier of the user's document documentType # Type of identification document country # ISO 3166-1 alpha-3 country code } } } "variables" : { "input": { "documentNumber": "123456789", "documentType": "DNI", "country": "CHL" } }

Possible Errors:

  • 401: Unauthorized - Missing or invalid authentication token
  • 404: Not Found - No account matches the provided filters
  • 400: Bad Request - Invalid input parameters
Order services

Create Order

It creates a buy or sell order, returning a UUID to identify it (orderId) and, depending on the payment method, a URL (providedData) to proceed to payment. It accepts amounts for crypto o currency, not both.

For authenticated calls without an email, this parameter must be included to associate the transaction to a specific account.

amountIn or amountOut must be provided as an input, but not both.

On ramp

Requires: destinationAddress, quoteId.

Off ramp

Requires: destinationAddress, quoteId.

Optional: email (required if user is not suthenticated with email), documentNumber (to facilitate bank reconciliation)

Data Description: see Order Rest 

mutation createOrder($input: OrderInput!) { createOrder(input: $input) { orderId amountIn amountOut documentNumber email metadata orderId paymentMethodId providedAction providedAddress quoteId symbolIn symbolOut externalId } } "variables": { "input": { "quoteId": "63e154dbc47d9176668a9af6", "amountIn": 1.100.000, "amountOut": 1, "email": "example@domain.com", #for API calls "documentNumber": null, "paymentMethodId": "632d7fe6237ded3a748112cf", # This value corresponds to the _id value returned after calling GetPaymentProviderList "destinationAddress": "0x40f9bf922c23c43acdad71Ab4425280C0ffBD697", # Will return error if address is invalid "symbolIn": "CLP", "symbolOut": "ETH", "metadata": null, "externalId":"12A2324A", "callbackUrl": "https://urlexample/mytracing/", } }

Get Order

Returns order information. Receives a orderId.

query getOrder($input: GetOrderInput!) { getOrder(input: $input){ orderId # unique identifier quoteId # quote id orderType # currency-crypto for on ramp, crypto-currency for off ramp symbolIn symbolOut amountIn amountOut email exchangeRate koyweFee partnerFee networkFee status # see the webhooks and states docs for more info outReceipt bankAccountId # bank account id for off ramps metaData externalId feesInFiat { #Only if the order has a partnerFee and is greather than 0 koyweFee netFee partnerFee } feesInUSD { #Only if the order has a partnerFee and is greather than 0 koyweFee #(koyweFee / exchangeRate) truncated to 4 digits after the comma netFee #(netFee / exchangeRate) truncated to 4 digits after the comma partnerFee #(partnerFee / exchangeRate) truncated to 4 digits after the comma } dates { confirmationDate paymentDate executionDate deliveryDate } destinationAddress # wallet address to send or receive tokens paymentMethodId logoIn # logo url for symbolIn logoOut # logo url for symbolOut refund { # refund details for off ramps dates { startDate processDate deliveredDate } destinationAddress transactionReceipt } errors { # error details for off ramps invalidWithdrawalsDetails { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } } } "variables": { "input": { "orderId": "02a5f0c7-b9bf-48e0-8b5d-190d2e2f7fc1" #Created when calling mutation Order } }

Get Order by ExternalId

Returns order information. Receives a externalId.

query getOrderByExternalId($input: GetExternalIdOrderInput!) { getOrderByExternalId(input: $input){ orderId # unique identifier quoteId # quote id orderType # currency-crypto for on ramp, crypto-currency for off ramp symbolIn symbolOut amountIn amountOut email exchangeRate koyweFee partnerFee networkFee status # see the webhooks and states docs for more info outReceipt bankAccountId # bank account id for off ramps metaData externalId feesInFiat { #Only if the order has a partnerFee and is greather than 0 koyweFee netFee partnerFee } feesInUSD { #Only if the order has a partnerFee and is greather than 0 koyweFee #(koyweFee / exchangeRate) truncated to 4 digits after the comma netFee #(netFee / exchangeRate) truncated to 4 digits after the comma partnerFee #(partnerFee / exchangeRate) truncated to 4 digits after the comma } dates { confirmationDate paymentDate executionDate deliveryDate } destinationAddress # wallet address to send or receive tokens paymentMethodId logoIn # logo url for symbolIn logoOut # logo url for symbolOut refund { # refund details for off ramps dates { startDate processDate deliveredDate } destinationAddress transactionReceipt } errors { # error details for off ramps invalidWithdrawalsDetails { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } } } "variables": { "input": { "externalId": "12A2324A" #Defined when calling mutation Order } }

Get Order(s) by txHash

Returns order(s) information. Receives a txHash.

query GetOrderByTxHash($input: GetTxHashOrderInput!) { getOrderByTxHash(input: $input) { orderId # unique identifier quoteId # quote id orderType # currency-crypto for on ramp, crypto-currency for off ramp symbolIn symbolOut amountIn amountOut email exchangeRate koyweFee partnerFee networkFee status # see the webhooks and states docs for more info outReceipt bankAccountId # bank account id for off ramps metaData externalId feesInFiat { #Only if the order has a partnerFee and is greather than 0 koyweFee netFee partnerFee } feesInUSD { #Only if the order has a partnerFee and is greather than 0 koyweFee #(koyweFee / exchangeRate) truncated to 4 digits after the comma netFee #(netFee / exchangeRate) truncated to 4 digits after the comma partnerFee #(partnerFee / exchangeRate) truncated to 4 digits after the comma } dates { confirmationDate paymentDate executionDate deliveryDate } destinationAddress # wallet address to send or receive tokens paymentMethodId logoIn # logo url for symbolIn logoOut # logo url for symbolOut refund { # refund details for off ramps dates { startDate processDate deliveredDate } destinationAddress transactionReceipt } errors { # error details for off ramps invalidWithdrawalsDetails { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } } } "variables": { "input": { "txHash": "0x7bd90e6285dbf85b48f0907288bdbd79ba082bc2c639640ie8234a5867cgd190" } }

List of past orders

Returns a list of all orders associated to the clientId or email specified when completing the user’s authentication.

pagesize: This value has a limit of 300, represents the number of responses per page.

pageNumber: Number of pages shown.

initDate: The initial date from which records are retrieved. Format: YYYY-MM-DD. Records from this date onwards will be included unless an ‘endDate’ is specified.

endDate: The end date until which records are retrieved. Format: YYYY-MM-DD. Only records up to this date will be included. If omitted, records up to the current date are returned.

query orders($input: PaginationInput!) { orders(input: $input) { pagination { totalCount pageSize pageNumber } data { orderId # unique identifier quoteId # quote id orderType # currency-crypto for on ramp, crypto-currency for off ramp symbolIn symbolOut amountIn amountOut email exchangeRate koyweFee partnerFee networkFee status # see the webhooks and states docs for more info outReceipt bankAccountId # bank account id for off ramps metaData externalId feesInFiat { #Only if the order has a partnerFee and is greather than 0 koyweFee netFee partnerFee } feesInUSD { #Only if the order has a partnerFee and is greather than 0 koyweFee #(koyweFee / exchangeRate) truncated to 4 digits after the comma netFee #(netFee / exchangeRate) truncated to 4 digits after the comma partnerFee #(partnerFee / exchangeRate) truncated to 4 digits after the comma } dates { confirmationDate paymentDate executionDate deliveryDate } destinationAddress # wallet address to send or receive tokens paymentMethodId logoIn # logo url for symbolIn logoOut # logo url for symbolOut refund { # refund details for off ramps dates { startDate processDate deliveredDate } destinationAddress transactionReceipt } errors { # error details for off ramps invalidWithdrawalsDetails { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } } } } "variables": { "input": { "pageNumber": 100, "pageSize": 1, "initDate": "2024-01-01", # optional "endDate": "2024-03-01", # optional } }

Add txHash Off Ramp order

Add txHash to an off ramp order. Checks hash is valid for the chosen network.

mutation SetTxHashOrder($input: TxHashOrderInputDto!) { setTxHashOrder(input: $input) { orderId message } } "variables": { "input": { "txHash": "0xcef85d0123ea3d2a3c4bdfaa6d13019c1b3d2aa6943e6ba853644d443ab83ad7", "orderId": "ec2af111-acdc-43bb-a0f3-eb1ed1800bbc" } }

Refund Order

Initiate a refund request for an off-ramp order due to errors in the fiat transfer details, returning the orderId and the status of the request.

mutation OffRampRefund($input: OrderRefundInputDto!) { offRampRefund(input: $input) { code data { orderId } message timestamp } } "variables": { "input": { "orderId": "ec2af111-acdc-43bb-a0f3-eb1ed1800bbc" } } #### Example of Error Response { "errors": [ { "message": "Refund already requested", "status": "INTERNAL_SERVER_ERROR" } ], "data": null } #### Example of Successful Response { "data": { "offRampRefund": { "code": "REFUND_000", "data": { "orderId": "ec2af111-acdc-43bb-a0f3-eb1ed1800bbc" }, "message": "ok", "timestamp": "2024-06-27T22:34:04.685Z" } } }

Reprocessing order

Service responsible for reprocessing an order in case of banking errors. The objective is to be able to finalize the transaction of converting crypto to the corresponding currency, where a transfer is made to the bank account associated with the order.

mutation UpdateOrderWithdrawalDetails($input: UpdateBankInTransactionInput!) { updateOrderWithdrawalDetails(input: $input) { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } "variables": { "input": { "orderId": "8bc5b15e-7d9a-4748-b343-cc7d01d20e5f", "destinationAddress": "665a3d05320291a30b6befef" // New bank account id without errors } }
Banking services

Create Bank Account

Creates a new bank account and saves it for future operations.

optional: bankCode, documentNumber, payoutMethodId (deprecated)

documentNumber is required when the user has not been KYC’d.

mutation createBankAccount($input: BankAccountInput!) { createBankAccount(input: $input) { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } "variables": { "input": { "bankCode": "SANTANDER", "accountNumber": "0123123123", "accountType": "checking", "countryCode": "CHL", "currencySymbol": "CLP", "documentNumber": "12345678", "email": "example@domain.com" } }

Colombian Bank validations

To avoid rejections, you need to take into account the requirements of the destination accounts according to the bank to which you are going to send the payment:

BankValidations
NEQUIMaximum account number size must be 11
DAVIVIENDAMinimum account number size must be 12
BANCOLOMBIAMaximum account number size must be 11
DAVIPLATAThe account number must start with 3 and the minimum size must be 10
BANCO CAJA SOCIAL BCSC SAMaximum account number size must be 11
BANCO DE BOGOTÁMaximum account number size must be 9
SCOTIABANK COLPATRIA SAMaximum account number size must be 10
UALAAccount number must be 15 numeric digits

Warning: The bankAccountNumber: Bank Account Number field must contain only numbers and be different from 0.

Get Bank Account

Returns a list of bank accounts the users has associated, filtered using countryCode, currencySymbol and email.

query getBankAccount($filters: FiltersBankAccount!) { getBankAccount(filters: $filters) { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } "variables": { "filters": { "countryCode": "CHL", "currencySymbol": "CLP", "email": "example@domain.com" } }

Delete Bank Account

Deletes a Bank Account from the lists of the client’s bank accounts.

mutation deleteBankAccount($input: DeleteBankAccountInputDto!) { deleteBankAccount(input: $input) { _id name bankCode countryCode currencySymbol accountNumber account accountType entityName } } "variables": { "input": { "_id": "63bd75901ea16ea6e23109b5", #Bank account identifier "email": "example@domain.com", "countryCode": "CHL", "currencySymbol": "CLP" } }

Get Bank Info by Country

Returns a list of available banks for a given countryCode.

query getBankInfoByCountry($countryCode: String!) { getBankInfoByCountry(countryCode: $countryCode) { bankCode name institutionName transferCode } } "variables": { "countryCode": "CHL" }
Last updated on