En esta sección podrás ver un flujo básico de llamados a la API de Koywe para compra y venta (aplica para ambas acciones).

/accounts

Este servicio es sólo para clientes que han delegado KYC.
La cuenta a crear o actualizar se basará en el correo electrónico proporcionado en la solicitud. Esto se puede hacer desde el cuerpo o mediante el token. Si se envían desde ambos lados, deben ser iguales.

Glosario

  • email: Dirección de correo electrónico que será asociada a la cuenta del usuario.

  • document:
    • documentNumber: Número de documento perteneciente a la persona que se va a registrar.
    • documentType: Tipo de documento relacionado al número de documento de la persona que se va a registrar.
    • country: País de emisión del documento.
    • isCompany: Tipo de persona a registrar. En caso de estar en true la cuenta a registrar va a ser de una persona legal o jurídica. Caso contrario, una persona natural.
    • others: Array de documentos secundarios.
      • documentNumber: Número de documento perteneciente a la persona que se va a registrar.
      • documentType: Tipo de documento relacionado al número de documento de la persona que se va a registrar.
      • country: País de emisión del documento.
  • address:
    • addressCountry: Lugar de residencia de la persona. No puede ser distinta de la del documento.
    • addressZipCode: Código postal de la residencia.
    • addressState: Nombre de la primera subdivisión del país de residencia. Podría ser estado, provincia, región, etc.
    • addressCity: Nombre de la ciudad de la residencia.
    • addressNeighborhood: Nombre de la subdivisión de la ciudad. Podría ser barrio, comuna, etc.
    • addressStreet: Dirección de calle con numeración, si la tuviera, donde la persona, jurídica o natural recide.
  • personalInfo:
    • names: Nombres de la persona natural o razón social de la persona jurídica.
    • firstLastname: Primer apellido de la persona natural. No aplica para persona jurídica.
    • secondLastname: Segundo apellido de la persona natural. No aplica para persona jurídica.
    • nationality: Nacionalidad de la persona natural. No aplica para persona jurídica.
    • gender: Género de la persona natural. Podría ser H para hombre, M para mujer u O para otro. No aplica para persona jurídica.
    • dob: Fecha de nacimiento de la persona o fecha de inicio de actividades para una persona jurídica. Se encuentra en formato YYYY-MM-DD
    • phoneNumber: Número de contacto asociado a la persona relacionado al país de registro.
    • activity: Profesión de la persona natural o actividad que realiza de la persona jurídica.

Paises soportados

ARG, CHL, COL, MEX, PER

Tipos de documentos por país soportado

  • Argentina -> DNI y CUIT
  • Chile -> RUT
  • Colombia -> Cedula Nacional (CED_CIU), Cédula de extranjería (CED_EXT) y NIT
  • México -> RFC y CURP
  • Perú -> DNI y RUC

Nacionalidades soportadas

  • ATG: Antigua y Barbuda
  • ARG: Argentina
  • BHS: Bahamas
  • BRB: Barbados
  • BLZ: Belice
  • BOL: Bolivia
  • BRA: Brasil
  • CAN: Canadá
  • CHL: Chile
  • COL: Colombia
  • CRI: Costa Rica
  • CUB: Cuba
  • DMA: Dominica
  • DOM: República Dominicana
  • ECU: Ecuador
  • SLV: El Salvador
  • GRD: Granada
  • GTM: Guatemala
  • GUY: Guyana
  • HTI: Haití
  • HND: Honduras
  • JAM: Jamaica
  • MEX: México
  • NIC: Nicaragua
  • PAN: Panamá
  • PRY: Paraguay
  • PER: Perú
  • PRI: Puerto Rico
  • KNA: San Cristóbal y Nieves
  • LCA: Santa Lucía
  • VCT: San Vicente y las Granadinas
  • SUR: Surinam
  • TTO: Trinidad y Tobago
  • USA: Estados Unidos
  • URY: Uruguay
  • VEN: Venezuela
  • AIA: Anguila(Reino Unido)
  • ABW: Aruba(Países Bajos)
  • BMU: Bermudas(Reino Unido)
  • BES: Bonaire, San Eustaquio y Saba(Países Bajos)
  • CYM: Islas Caimán(Reino Unido)
  • SGS: Islas Georgias del Sur y Sandwich del Sur(Reino Unido)
  • GRL: Groenlandia(Dinamarca)
  • GLP: Guadalupe(Francia)
  • FLK: Islas Malvinas(Reino Unido)
  • MTQ: Martinica(Francia)
  • MSR: Montserrat(Reino Unido)
  • ANT: Antillas Neerlandesas(Países Bajos)
  • TCA: Islas Turcas y Caicos(Reino Unido)
  • VGB: Islas Vírgenes Británicas(Reino Unido)
  • VIR: Islas Vírgenes de los Estados Unidos(.UU)

/Auth

Primero, debes autenticarte. Sugerimos agregar el email del usuario, para usar el JWT en los siguientes llamados.

GetCurrencyTokens (on ramp) GetTokenCurrency (off ramp)

Carga la lista de pares para ver los currencies y tokens disponibles y mostrarlos al usuario.

/payment-providers para on ramp o /payout-providers para off ramp

On ramp: Carga la lista de medios de pago disponibles. En este endpoint podrás encontrar los datos de transferencia para cada país, por lo que puede ser un buen momento para mostrarlos al usuario si es que selecciona ese medio de pago.

Off ramp: Carga la lista de medios de dispersión disponibles. Podrás encontrar los precios y tiempos de cada uno.

Post /quotes

Teniendo ambas monedas ingresadas, fiat y crypto, el usuario debe ingresar un monto a recibir o a pagar, para poder obtener una cotización. Con la respuesta de la cotización, el usuario podrá conocer exactamente cuánto pagará en comisiones y recibirá al concretarse la operación. Opcionalmente, podemos pedir a la API que guarde la cotización y la mantenga vigente por algunos segundos. En este caso, el quoteId lo podemos guardar para el siguiente paso.

¡Pruébalo!
Request
  curl --location --request POST 'https://api.koywe.com/rest/quotes' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "amountIn": 1000,
      "symbolIn": "USDC Polygon",
      "symbolOut": "CLP",
      "executable": false
  }'

Agregando un JWT de autenticación en el header y executable: true al request, obtendrás un quoteId que podrá ser usado para crear la orden en el siguiente paso. Este quote tiene una duración de 5 minutos.

Post /orders

Sólo basta con confirmar la orden. Si el quoteId sigue válido, sólo necesitamos incluir la billetera o cuenta de destino, el documentNumber del usuario (si es que no lo tuviera aún), y opcionalmente un campo de metadata para que puedas identificar la orden en tu sistema.

Para off ramps necesitarás crear una cuenta bancaria para el usuario. Revisa los docs para ver cómo hacer esto. El id del bankAccount debe ser ingresado en el campo destinationAddress del request.

¡Pruébalo!
Request
  curl --location --request POST 'https://api.koywe.com/rest/orders' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer superJWT' \
  --data-raw '{
      "quoteId": "64c9a26af1fada33f2e9e5d7",
      "destinationAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "metadata": "Sending some USDC to Vitalik",
      "documentNumber": "111243235"
  }'

a API devolverá un orderId, los detalles del pago (una url para redirigir a tu usuario o los detalles de la transferencia bancaria), e información para que sigas el proceso. Debería verse algo así:

{
  "data": {
    "createOrder": {
      "amountIn": 822000,
      "amountOut": 1000,
      "documentNumber": "111243235",
      "email": "email@domain.com",
      "metadata": "Sending some USDC to Vitalik",
      "orderId": "27d1a1c0-ff5e-4d5a-8893-a3ac2bb121e7",
      "providedAction": "https://url.to/some-path", // This should be a URL to a payment method or the callback you provided
      "providedAddress": "Koywe SpA\nCta Cte 6824645\n76.215.256-2\nBanco Santander\ntef@koywe.com", // where to transfer the money, in case of wire
      "symbolIn": "CLP",
      "symbolOut": "USDC"
    }
  }
}

Si el quote ya había expirado, se puede generar un nuevo quote (obligatorio a partir del 6 de noviembre del 2023) o llamar a createOrder con los mismos parámetros para tener un quote y orden al mismo tiempo.

Una vez recibido el orderId podemos guardarlo, asociándolo al usuario.

Resta esperar los llamados al webhook desde nuestra API o consultar Get /order con el id guardado cada cierto tiempo.