Version: 📄 MX

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.

info

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:

POST url externa 
{
    "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)

tip

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:

Ejemplo 1
{
    "KeyA": "value",
    "KeyB": "value"
}

Ejemplo 2
{
    "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)

tip

Bsale realiza la redirección hacia la URL. Se envia VALUE si es que lo requiere.

Flujo de una transacción

img alt

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

info

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)

Body
{
    "id": "673f8a9282b5bN",
    "authorizationCode": "3452",
    "data": {
        "cardNumber": "3152",
        "quota": 0,
        "quotaAmount": 19990,
        "payType": "Credit",
        "status": "completed",
        "transactionDate": "2024-10-08T12:08:55Z"
    }
}

Response
{
    "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)

Body
{
    "id": "673f8a9282b5bN",
    "msg": "TimeOut",
    "data": "información adicional del pago.(Object)"
}

Response
{
    "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)

Body
{
    "msg": "Transacción iniciada, id: "
}

Response
{
    "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)

Response
{
    "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)

Body
{
    "authorizationCode": "3452",
    "data": {
        "cardNumber": "3152",
        "status": "completed",
        "transactionDate": "2024-10-08T12:08:55Z"
    }
}

Response
{
    "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

Response ok
{
    "code": "codigo de error (400, 404, 500)",
    "errors": {
        "msg": "mensaje de error",
        "data": "body enviado"
    }
}

Response error
{
    "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 👋

Pagos Tienda en línea (Bcash)

Inicio de transacción​

Parámetros​

Autentificación​

Respuesta MPE​

Parámetros​

Flujo de una transacción​

Endpoints​

POST Success​

Parámetros​

Atributos​

POST Fail​

Parámetros​

Atributos​

POST Log​

Parámetros​

Atributos​

GET State​

Parámetros​

Atributos​

POST Pending​

Parámetros​

Atributos​

Tipos de respuesta​

SandBox​

Ayuda​

Inicio de transacción

Parámetros

Autentificación

Respuesta MPE

Parámetros

Flujo de una transacción

Endpoints

POST Success

Parámetros

Atributos

POST Fail

Parámetros

Atributos

POST Log

Parámetros

Atributos

GET State

Parámetros

Atributos

POST Pending

Parámetros

Atributos

Tipos de respuesta

SandBox

Ayuda