Flujo Básico API

​

/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. Para ello, tienes dos maneras:

• De manera directa, si ya eres cliente, puedes hacerlo con un secret y el clientId mediante el uso del servicio POST /auth. Sugerimos agregar el email del usuario, para usar el JWT en los siguientes llamados.
• Solo disponible para clientes con KYC no delegado. En dos pasos, a traves del correo electrónico consumiendo el endpoint POST /auth/validate. Te enviaremos un código para validarlo y luego confirmandolo con POST /auth/code.

​

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

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: No es requerido.

​

/bank-accounts

Registro de cuentas bancarias.

On ramp: Requerido solo en caso de usar el método de pago de STP.

Off ramp: Requerido. Antes de poder crear una orden necesitamos registrar la cuenta bancaria donde se mandara el dinero.

​

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.

  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.

  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"
    }
  }
}

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.