Skip to main content

Guía de Integración

El objetivo de la siguiente guía es llevarte de la mano en un proceso de integración óptimo. Para esto seguiremos una serie de pasos que permitirán el desarrollo de la integración, desde el registro de usuarios en la plataforma de inversión, incluyendo el proceso de onboarding, pasando por el fondeo de la cuenta y las operaciones de trading.

El único requisto previo para poder llevar a cabo esta serie de pasos es haber realizado una autenticación exitosa. Recuerda que en todos los llamados a la API debes pasar en el header "Authorization" el token de autenticación.

Paso 1: Registro de Usuario​

El primer paso recomendado para iniciar el proceso de integración, es el registro de tu primer usuario.

Aquí tienes un ejemplo de como crear tu primer usuario:

  POST /v1/user

Cuerpo de la Solicitud

  {
      "externalId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "name": "Anakin",
      "familyName": "Skywalker",
      "email": "anakin.skywalker@tatooine.com",
      "phone": "+506897654231",
      "countryCode": "CRI"
  }

En el campo "externalId" puedes pasar opcionalmente un id externo para el usuario. En este caso recomendamos pasar el id de tu usuario en tu plataforma para así mejorar la identificación o equivalencia entre los usuarios de ambas plataformas. El campo es opcional con una longitud máxima de 50 caracteres.

El campo countryCode debe ser un código de país según la lista retornada por el endpoint /onboarding/tax-countries.

Ejemplo de Respuesta

  {
      "id": "7c44e25f-7e0a-4c4e-b114-3d119bdff290",
      "partnerId": "015ae137-31aa-467f-bfc4-f99536381a81",
      "externalId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "name": "Anakin",
      "familyName": "Skywalker",
      "email": "anakin.skywalker@tatooine.com",
      "phone": "+506897654231",
      "countryCode": "CRI"
      "dateCreated": "2019-08-24T14:15:22Z",
      "dateModified": "2019-08-24T14:15:22Z"
  }

Consulta aquí la guía detallada de la API de Usuarios.

Paso 2: Verificación de Identidad​

Una vez que hayas registrado tu primer usuario, debes proceder con el proceso de verificación de identidad. Este proceso consiste en brindar evidencia de la identidad y prueba de vida del usuario subiendo 3 documentos:

  • Foto de la parte frontal del documento de identidad del usuario
  • Foto de la parte trasera del documento de identidad del usuario
  • Selfie en vivo del usuario para realizar la prueba de vida

Notas:

  • La foto de la parte trasera no aplica para todos los tipos de documentos, como por ejemplo pasaporte. En este caso se debe subir únicamente la parte frontal y especificar en el llamado que es un documento que solamente contiene parte frontal.
  • El proceso de verificación de identidad del usuario puede fallar debido a varios factores como la calidad de las imágenes, validez de las mismas (como por ejemplo que no sean fotos tomadas de una pantalla, etc)

Subiendo Foto de la Parte Frontal de la Identificación del Usuario​

  POST /v1/onboarding/{userId}/front-side-of-id

Cuerpo de la Solicitud

  {
      "onlyFront": false,
      "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2w......"
  }

Notas:

  • Para documentos de identidad que solo tienen una cara, como pasaportes, enviar onlyFront en true. En este caso no será necesario subir una parte trasera.
  • Actualmente se soportan imagenes en formato JPG, JPEG y PNG. Recordar pasar la data en formato base64.

Subiendo Foto de la Parte Trasera de la Identificación del Usuario​

  POST /v1/onboarding/{userId}/back-side-of-id

Cuerpo de la Solicitud

  {        
      "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2w......"
  }

Subiendo Foto de la Selfie del Usuario​

  POST /v1/onboarding/{userId}/selfie

Cuerpo de la Solicitud

  {        
      "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2w......"
  }

Una vez que hayas subido los documentos necesarios para la verificación de identidad del usuario, puedes proceder verificar los resultados de la misma en el próximo paso.

Paso 3: Comprobar Status de la Verificación de Identidad​

  POST /v1/onboarding/{userId}/id-verification-status

Respuesta

  {
      "id": "0fcae3fc-b052-4359-a85e-c3125551734d",
      "userId": "6e971654-d66e-42c6-9b0c-0811058ed90a",
      "dateCreated": "2025-05-09T23:19:25.66",
      "dateModified": "2025-05-09T23:28:50.11",
      "onboardingStatus": "ONBOARDING_FINISHED",
      "firstName": "ANAKIN",
      "lastName": "SKYWALKER",
      "country": "NIC",
      "address": "Hutt's Alley",
      "dateOfBirth": "1990-09-12",
      "taxID": "DNI12097500050",
      "gender": "M",
      "lastStatusChange": "2025-05-09T23:28:49.567",
      "completed": true,
      "result": "OK",
      "score": 97.20,
      "reasonMsg": "Passed all tests: Face Recognition, Antifraud module, ID Verification, Liveness Detection"
  }

Notas:

  • Una vez que el valor del campo "result" es "OK", la verificación de identidad se da por válida
  • Cuando la verificación de identidad es válida, ya se puede proceder a enviar los datos necesarios para crear el perfil de trader del usuario

Paso 4: Registro de Perfil de Trader​

Una vez que se haya verificado exitosamente identidad del usuario, puedes proceder a enviar todos los datos necesarios para registrar el perfil de trader del usuario. Esta información es requerida para que nuestro broker cree la cuenta de inversionista en la bolsa de valores de los Estados Unidos de América.

  POST /v1/onboarding/{userId}/trader-profile

Cuerpo de la Solicitud

  {
      "legalFirstName": "Anakin",
      "legalLastName": "Skywalker",
      "countryOfTaxResidence": "CRI",
      "countryOfBirth": "CRI",
      "countryOfCitizenship": "CRI",
      "city": "Tres Rios",
      "state": "Cartago",
      "dob": "2000-02-01",
      "gender": "M",
      "maritalStatus": "S",
      "taxID": "123456789",
      "residentialAddress": "Condominio Palmeras, Guácima, Cartago",
      "unitAptNumber": "B51",
      "postalCode": "10101",
      "annualHouseholdIncomeRange": "R50K",
      "investibleLiquidAssetsRange": "R20K",
      "accountFundingSource": "savings",
      "employmentStatus": "employed",
      "nameOfEmployer": "Acme Corporation",
      "employerAddress": "San José, Avenida Central 101",
      "occupationJobTitle": "Engineer",
      "permanentResident": false,
      "isVisaHolder": false,
      "visaType": null,
      "visaExpirationDate": null,
      "dateOfDepartureFromUSA": null,
      "trustedContactFirstName": null,
      "trustedContactLastName": null,
      "trustedContactEmailAddress": null,
      "trustedContactPhoneNumber": null,
      "isAffiliatedExchangeOrFinra": false,
      "isControlPerson": false,
      "isPoliticallyExposed": false,
      "inmediateFamilyExposed": false
  }

Notas:

  • Tomar en cuenta que no todos los campos en este endpoint son requeridos.
  • Algunos campos solamente son requeridos para usuarios residentes en los Estados Unidos de América.
  • Los campos de "trusted contact" también son opcionales.
  • Puedes consultar la API de Onboarding para ver de manera detallada la documentación de cada uno de los campos, así como para saber cuales son requeridos.

Puedes consultar el perfil de trader del usuario para conocer, entre otras cosas, el status de su cuenta de inversión.

Paso 5: Consultando el Perfil de Trader del Usuario​

Una vez que el profile de trader del usuairo ha sido enviado, puedes consultarlo con el siguiente endpoint GET:

  GET /v1/onboarding/{userId}/trader-profile

Respuesta

  {
      "id": "41b2af64-0f31-4895-8121-e870244db5b6",
      "userId": "6e971654-d66e-42c6-9b0c-0811058ed90a",
      "country": "CRI",
      "countryName": "Costa Rica",
      "state": "Cartago",
      "stateName": "Cartago",
      "phone": "+505897654231",
      "city": "Tres Rios",
      "legalFirstName": "Anakin",
      "legalLastName": "Skywalker",
      "dateOfBirth": "2000-02-01T00:00:00",
      "taxID": "DNI75983614",
      "residentialAddress": "Condominio Palmeras, Guacima, Cartago",
      "unitAptNumber": "B51",
      "postalCode": "10101",
      "emailAddress": "anakin.skywalker@tatooine.com",
      "countryOfTaxResidence": "CRI",
      "permanentResident": false,
      "countryOfBirth": "CRI",
      "countryOfCitizenship": "CRI",
      "isVisaHolder": false,
      "visaType": null,
      "visaExpirationDate": null,
      "dateOfDepartureFromUSA": null,
      "annualHouseholdIncomeRange": "R50K",
      "investibleLiquidAssetsRange": "R20K",
      "accountFundingSource": "savings",
      "employmentStatus": "employed",
      "nameOfEmployer": "Acme Corporation",
      "employerAddress": "San José, Avenida Central 101",
      "occupationJobTitle": "Engineer",
      "trustedContactFirstName": null,
      "trustedContactLastName": null,
      "trustedContactEmailAddress": null,
      "trustedContactPhoneNumber": null,
      "isAffiliatedExchangeOrFinra": false,
      "isControlPerson": false,
      "isPoliticallyExposed": false,
      "inmediateFamilyExposed": false,
      "dateCreated": "2025-05-09T23:49:51.53",
      "dateModified": "2025-05-09T23:55:35.677",
      "brokerAccountNumber": "823790788",
      "brokerAccountStatus": "ACTIVE",
      "statusReason": null,
      "gender": "M",
      "maritalStatus": "S"
  }

El campo "brokerAccountStatus" es de gran importancia porque nos dice si el profile del usuario ya está activo en la plataforma del broker. Una vez que el profile ya está e el estado ACTIVE, se puede proceder con el resto los pasos del flujo, como son el fondear la cuenta de inversiones y el de enviar órdenes de compra o venta de stocks en nombre de tus usuarios.

Paso 6: Fondeo​

Para poder iniciar transacciones de trading, o sea, compra y venta de stocks, es necesario que la cuenta de inversión del usuario tenga fondos. A continuación se muestra un ejemplo de como cargar fondos (hacer un depósito):

  POST /v1/funding

Cuerpo de la Solicitud​

  {
      "userId": "4be3c6d1-2d49-4843-b5f4-1c63abde443e",
      "direction": "DEPOSIT",
      "amount": "100",
      "externalId": "a1d27847-0645-4e95-8698-5b09a516d932"
  }

Ejemplo de Respuesta​

  {
      "id": "bbdcf204-ef0c-4612-95f8-b6329211b99c",
      "userId": "4be3c6d1-2d49-4843-b5f4-1c63abde443e",
      "direction": "DEPOSIT",
      "amount": 100,
      "fee": 2,
      "netAmount": 98,
      "partnerId": "29e16674-3baa-4ae6-b13d-d4384499d16e",
      "externalId": "4a4f8547-9ef1-4054-a2c9-699da47ebd20",
      "status": "pending",
      "statusReason": "",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "completedAt": "2019-08-24T14:15:22Z"
  }

Notas:

  • El monto de las transacciones de fondeo en TraderPal Connect siempre está dado en dólares americanos.
  • El modelo de fondeo con TraderPal Connect está basado en un modelo de compensaciones, en el cual, el partner es responsable de debitar en su propia plataforma el monto a fondear de la cuenta del usuario (sea esta una cuenta bancaria, un wallet digital, por citar algunos ejemplos). TraderPal Connect aplica un crédito a la cuenta de inversiones del usuario desde una cuenta prefondeada en la plataforma de nuestro broker. Luego en cada liquidación, el partner debe transferir a una cuenta bancaria en USA con cierta periodicidad a definir con TraderPal, el total de los depósitos del período para alimentar nuevamente la cuenta prefondeada.

Paso 7: Trading​

Una vez que la cuenta del usuario ya tiene fondos, es posible enviar una orden de compra de un stock.

A continuación se muestra un ejemplo de como enviar una orden de compra de 50 dólares en acciones de Apple:

  POST /v1/orders

Cuerpo de la Solicitud​

  {
      "userId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "symbol": "AAPL",
      "qty": 0,
      "amount": 50,
      "side": "buy",
      "externalId": "540d78ab-9d74-4ae3-8ffb-c96a959709ab"
  }

Ejemplo de Respuesta​

  {
      "id": "e1d73a31-2495-4f68-aa88-e251174552f4",
      "userId": "2946445a-f37d-4aaa-8327-e372adf763b8",
      "symbol": "AAPL",
      "qty": 0,
      "ammount": 50,
      "commission": 0.25,
      "side": "buy",
      "status": "pending"
  }

Próximos Pasos​