Pagos Tienda en línea (Bcash)
Mediante esta API se permite que medios de pagos para ecommerce se integren con más facilidad a los comercios manejados por Bsale. A continuación, se detallan el flujo de la transacción y los endpoint disponibles.
Url base https://urltienda.bsalemarket.com/
Inicio de transacción
Para iniciar una transacción Bsale realiza una petición POST al endpoint dado por el medio de pago externo (MPE).
- POST URL Externa
Para que el MPE tenga constancia del comercio al que pertenece la transacción se envia el siguiente mensaje en el body:
{
"py_token": "47914de619d606d5c796500723f62715cd2fbef2",
"currency": "CLP",
"amount": 10710,
"order": "502",
"payment": {
"email": "andreas@mp.io",
"items": {
"sku": "TOOP1988",
"quantity": "1",
"amount": 10710
}
},
"client": {
"token": "c623a9bc9c3f14a0...310a542d9dadd08f"
}
}
Parámetros
- py_token, token de la transaccion. Debe ser usado para los demas Endpoints. (String)
- amount, monto de la transaccion. (Integer)
- order, número de orden. (Integer)
- payment, Información general dada por el medio de pago integrado a Bsale. (Object)
- client, Información de la instancia que integro el medio de pago. (Object)
clients
puede ser algun dato de cliente, de contato, id, número, token, etc, algo que identifique al cliente que contratópayments
algún dato requerido por el MPE para procesar el pago
Autentificación
Si el endpoint necesita credenciales, el MPE debe entregar dicha credencial que será usada en los headers de la petición. Ej:
{
"KeyA": "value",
"KeyB": "value"
}
{
"EXT_ID": 1,
"AUTH": {
"access-Sign": "bsale-gw Integration"
},
"COMMERCE_DATA": {
"token": "c623a9bc9c3f14a0...310a542d9dadd08f"
},
"INIT_TRANSACTION_URL": "http://dev002.herokkuapp.com:8765/bsale-test/pay"
}
Respuesta MPE
Bsale espera que la petición entregue un mensaje JSON que contenga:
{
"url": "http://dev002.herokkuapp.com:8765/bsale-test/pay",
"value": "bsale-gw Integration",
"key": "c623a9bc9c3f14a0...310a542d9dadd08f"
}
Parámetros
- url, dirección a la cual Bsale redireccionará. (Obligatorio, String)
- value, valor que sea necesario para la redirección. (String)
- key, nombre que tendrá el valor (String)
Bsale realiza la redirección hacia la URL. Se envia VALUE
si es que lo requiere.
Flujo de una transacción
- El flujo inicia con el comprador seleccionando el medio de pago externo.
- El Ecommerce (controlado por Bsale) envía la petición de inicio de transacción (ver inicio de transacción) al medio de pago.
- Bsale realiza la redirección hacia la dirección obtenida.
- El navegador web del cliente realiza la peticion https hacia el medio de pago externo.
- El medio de pago responde al cliente con el formulario para realizar el proceso de pago.
- El medio de pago realiza una peticion a
/v1/payment/fail/:py_token
o/v1/payment/success/:py_token
dependiendo del resultado de la transacción, y este recibe la URL del comercio al cual debe redireccionar. - El medio de pago redirecciona al cliente hacia la URL obtenida.
Endpoints
Url base https://bcash.bsale.io/
POST Success
- POST
/v1/payment/success/:py_token
Endpoint de redirección, se encarga de registrar las transacciones que se realizaron de forma exitosa.
Parámetros
- py_token, Es el token con el que llegó al sistema de pago. (ver inicio de transacción)
{
"id": "673f8a9282b5bN",
"authorizationCode": "3452",
"data": {
"cardNumber": "3152",
"quota": 0,
"quotaAmount": 19990,
"payType": "Credit",
"status": "completed",
"transactionDate": "2024-10-08T12:08:55Z"
}
}
{
"code": 200,
"data": {
"token": "py_token ingresado",
"order": "numero de orden",
"status": "estado de la transacción",
"amount": "monto de la transacción",
"redirectTo": "dirección donde el medio de pago debe redirigir"
}
}
Atributos
Atributo | Descripción | Tipo dato |
---|---|---|
id | id de la transaccion | String |
authorizationCode | Código de autorización de la transacción. (Obligatorio) | String |
cardNumber | ultimos 4 digitos (Obligatorio) | String |
quota | cantidad de cuotas (0, 1, 2, ...) (Obligatorio) | Integer |
quotaAmount | monto cada cuota (Obligatorio) | Integer |
payType | tipo de pago (débito, crédito sin cuotas, crédito con cuotas, etc) | String |
status | estado de la transacción | String |
transactionDate | fecha de la transacción | String |
POST Fail
- POST
/v1/payment/fail/:py_token
Endpoint de redirección, se encarga de registrar las transacciones que se realizaron de forma errónea.
Parámetros
- py_token, Es el token con el que llegó al sistema de pago. (ver inicio de transacción)
{
"id": "673f8a9282b5bN",
"msg": "TimeOut",
"data": "información adicional del pago.(Object)"
}
{
"code": 200,
"data": {
"token": "47914de619d606d5c796500723f62715cd2fbef2",
"order": "502",
"status": "fail",
"amount": 10710,
"redirectTo": "https://nuevo-entrenamiento.bsalemarket.com/checkout/success/47914de619d606d5c796500723f62715cd2fbef2"
}
}
Atributos
Atributo | Descripción | Tipo dato |
---|---|---|
id | id de la transaccion | String |
msg | motivo del fallo de la transacción | String |
data | información adicional del pago (Obligatorio) | Object |
POST Log
- POST
/v1/payment/log/:py_token
Este endpoint se encarga de registrar logs en la transacción.
Parámetros
- py_token, Es el token con el que llegó al sistema de pago. (ver inicio de transacción)
{
"msg": "Transacción iniciada, id: "
}
{
"code": 200,
"data": {
"msg": "ok"
}
}
Atributos
Atributo | Descripción | Tipo dato |
---|---|---|
msg | Mensaje que se almacenará en el log de la transacción | String |
GET State
- GET
/v1/payment/state/:py_token
Este endpoint se encarga de mostrar la información que ya esta almacenada en la transacción.
Parámetros
- py_token, Es el token con el que llegó al sistema de pago. (ver inicio de transacción)
{
"code": 200,
"data": {
"token": "47914de619d606d5c796500723f62715cd2fbef2",
"order": "502",
"status": "fail",
"amount": 10710
}
}
Atributos
Atributo | Descripción | Tipo dato |
---|---|---|
token | Token de la transacción | String |
order | número de la orden | String |
status | Estado de la transacción | String |
amount | Monto de la transacción. | Integer |
POST Pending
- POST
/v1/payment/pending/:py_token
Este endpoint recibe los pagos en pending (transferencia, cupones, etc).
Parámetros
- py_token, Es el token con el que llegó al sistema de pago. (ver inicio de transacción)
{
"authorizationCode": "3452",
"data": {
"cardNumber": "3152",
"status": "completed",
"transactionDate": "2024-10-08T12:08:55Z"
}
}
{
"code": 200,
"data": {
"token": "47914de619d606d5c796500723f62715cd2fbef2",
"order": "502",
"status": "success",
"amount": 10710
}
}
Atributos
Atributo | Descripción | Tipo dato |
---|---|---|
authorizationCode | Código de autorización de la transacción. (Obligatorio) | String |
data | información adicional del pago (Obligatorio) | Object |
Tipos de respuesta
{
"code": "codigo de error (400, 404, 500)",
"errors": {
"msg": "mensaje de error",
"data": "body enviado"
}
}
{
"code": "codigo de exito (200, 201)",
"data": {
"msg": "mensaje de error",
"data": "body enviado"
}
}
SandBox
- Para generar un ambiente de pruebas deberá solicitar a ayuda@bsale.app o en la comunidad de slack, indícanos una url para generar la petición inicial de transacción.
- Cada medio de pago tiene un panel de configuración que el seller accede. El token de acceso es parte de una configuración genérica.
- Bsale puede dar soporte a parámetros en la url en caso de ser requeridos.
- Si el medio de pago externo trabaja con pagos asíncronos, deberá incluir el endpoint de "pending" para finalizar el flujo.
Ayuda
- Si necesitas aprender como trabaja Bsale de forma general puedes revisar nuestra base de conocimiento.
- Si tienes una duda puedes comunicarte con nosotros ingresando a la comunidad de slack 👋