Botón Bancolombia ofrece varias funcionalidades que permiten a los comercios procesar transacciones y conocer su estado en línea
Funcionalidades
- Realizar transferencias entre cuentas de ahorro y corriente Bancolombia para ventas digitales.
- Hacer consultas del estado de las transacciones.
Datos de prueba
Para realizar pruebas del producto de APIs de Botón Bancolombia puede utilizar los datos que se encuentran en el siguiente archivo: Datos de prueba
Callback
Funcionalidad que nos permite notificarle al comercio o a la pasarela de pago el resultado final de la transacción. Para habilitar esta opción, es necesario enviar la URL de notificación en el campo "confirmationURL" de la operación POST “registry”, en caso de no enviarla, no se llevará a cabo.
Campos que se envían en el Callback
| Campo | Tipo | Descripción |
|---|---|---|
| commerceTransferButtonId | String | HASH que identifica el Botón Bancolombia del comercio |
| requestDate | DateTime | Fecha en la que se registró la orden |
| transferCode | String | Identificador único de la transferencia |
| transferAmount | Number | Monto de la transacción |
| transferState | String | Estado de la transacción |
| transferStateDescription | String | Descripción del resultado de la transacción |
| transferVoucher | String | Número de comprobante de la transacción. |
| transferDate | Date | Fecha en la que se aprobó o rechazó la transacción. |
| sign | String | Firma que permitirá validar la integridad del request generado por Bancolombia |
¿Cómo generar el sign?
Para generar este valor, debe concatenar los siguientes valores: [apiKey~commerceTransferButtonId~transferCode~tranferAmount~transferState]
Una vez concatenados debe cifrar utilizando el algoritmo SHA512.
Por ejemplo, al concatenar los datos mencionados debe obtener algo muy similar a esto: 5Fj8eK4rlyUd252L48herdrnEO~w0mp1B0toN~_CeoHUM7C65~200.00~rejected
Y al crear el HASH de la cadena resultante, debe obtener el sign como se muestra a continuación: b6f7bc914b69824df799db0ad7c9bb26
- Protocols: HTTPS
production
development
https://sbapi.bancolombia.com
Base Gateway API Endpoint
Paths
/transfer/action/registry
post /transfer/action/registry
Button
Registrar intención de compra.
El API de Registrar Transferencia tiene como funcionalidad enviar la información de la intención de compra y obtener el código único de la transferencia.
OAuth - Provider from OTP Pymes - Flow Application
OAuth - Provider from OTP Pymes - Flow Application
(oauth2 application)
Proveedor de OAuth para autenticación con One Time Password(OTP) para Pymes
Token URL
https://api.us.apiconnect.ibmcloud.com/bancolombiabluemix-dev/sandbox/v1/security/oauth-otp-pymes/oauth2/token
Scopes
Transfer-Intention:write:app
Registro de intención de compra de un cliente por parte de un comercio para el pago a través de Botón Bancolombia
reqTransferencesRegistry
Required in body
object
Datos necesarios para registrar la intención de compra.
Content-Type
Optional in header
string
application/json
application/vnd.bancolombia.v1+json
application/vnd.bancolombia.v1+json
Accept
Optional in header
string
application/json
application/vnd.bancolombia.v1+json
191e9de9-8850-44bb-b2a5-6429586975ab
application/vnd.bancolombia.v1+json
191e9de9-8850-44bb-b2a5-6429586975ab
200
Successful response.
400
Error in the request.
401
Incorrect credentials.
403
You do not have permissions to access the resource.
404
Resource not found.
409
Resource state has conflicts with data of the request.
500
Internal server error.
502
Error in the service provider response.
503
Service unavailable.
504
Service provider response time exceeded.
Example Request
Example Response
POST https://sbapi.bancolombia.com/v2/operations/cross-product/payments/payment-order/transfer/action/registry
Try this operation
No response. This is a mixed content call. It is not possible to test HTTP APIs from an HTTPS secured Portal site and vice versa.
No response. This is a cross-origin call. Make sure the server accepts requests from this portal. Or if using self-signed SSL certificates then paste the URL above into your browser to accept the certificate before trying again (On Internet Explorer it must be the same browser tab.).
/transfer/{transferCode}/action/validate
get /transfer/{transferCode}/action/validate
Button
Consultar el estado de una transferencia.
El API de Consultar Transferencia tiene como funcionalidad consultar el estado de la transacción.
OAuth - Provider from OTP Pymes - Flow Application
OAuth - Provider from OTP Pymes - Flow Application
(oauth2 application)
Proveedor de OAuth para autenticación con One Time Password(OTP) para Pymes
Token URL
https://api.us.apiconnect.ibmcloud.com/bancolombiabluemix-dev/sandbox/v1/security/oauth-otp-pymes/oauth2/token
Scopes
Transfer-Intention:read:app
Consulta del estado de una transferencia a través de su código único de identificación de transferencia
transferCode
Required in path
string
Identificador único de la transferencia.
Accept
Optional in header
string
application/json
application/vnd.bancolombia.v1+json
191e9de9-8850-44bb-b2a5-6429586975ab
application/vnd.bancolombia.v1+json
191e9de9-8850-44bb-b2a5-6429586975ab
200
Successful response.
400
Error in the request.
401
Incorrect credentials.
403
You do not have permissions to access the resource.
404
Resource not found.
409
Resource state has conflicts with data of the request.
500
Internal server error.
502
Error in the service provider response.
503
Service unavailable.
504
Service provider response time exceeded.
Example Request
Example Response
GET https://sbapi.bancolombia.com/v2/operations/cross-product/payments/payment-order/transfer/{transferCode}/action/validate
Try this operation
No response. This is a mixed content call. It is not possible to test HTTP APIs from an HTTPS secured Portal site and vice versa.
No response. This is a cross-origin call. Make sure the server accepts requests from this portal. Or if using self-signed SSL certificates then paste the URL above into your browser to accept the certificate before trying again (On Internet Explorer it must be the same browser tab.).
/bancolombia-button-transference-management/health
head /bancolombia-button-transference-management/health
Operación de monitoreo
OAuth - Provider from OTP Pymes - Flow Application
OAuth - Provider from OTP Pymes - Flow Application
(oauth2 application)
Proveedor de OAuth para autenticación con One Time Password(OTP) para Pymes
Token URL
https://api.us.apiconnect.ibmcloud.com/bancolombiabluemix-dev/sandbox/v1/security/oauth-otp-pymes/oauth2/token
Scopes
Transfer-Intention:write:app
Registro de intención de compra de un cliente por parte de un comercio para el pago a través de Botón Bancolombia
Transfer-Intention:read:app
Consulta del estado de una transferencia a través de su código único de identificación de transferencia
Accept
Optional in header
string
application/json
application/vnd.bancolombia.v1+json
191e9de9-8850-44bb-b2a5-6429586975ab
application/vnd.bancolombia.v1+json
191e9de9-8850-44bb-b2a5-6429586975ab
200
Successful response.
Example Request
Example Response
HEAD https://sbapi.bancolombia.com/v2/operations/cross-product/payments/payment-order/bancolombia-button-transference-management/health
Try this operation
No response. This is a mixed content call. It is not possible to test HTTP APIs from an HTTPS secured Portal site and vice versa.
No response. This is a cross-origin call. Make sure the server accepts requests from this portal. Or if using self-signed SSL certificates then paste the URL above into your browser to accept the certificate before trying again (On Internet Explorer it must be the same browser tab.).
Definitions
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"commerceTransferButtonId",
"transferReference",
"transferAmount",
"commerceUrl",
"confirmationURL"
],
"properties": {
"commerceTransferButtonId": {
"type": "string",
"description": "HASH que identifica el botón de transferencia del comercio.",
"example": "h4ShG3NER1C",
"maxLength": 50
},
"transferReference": {
"type": "string",
"description": "Código de referencia de la transacción para el comercio.",
"example": "1002345678",
"maxLength": 100
},
"transferDescription": {
"type": "string",
"description": "Descripción de la transferencia.",
"example": "Compra en Telovendo",
"maxLength": 255
},
"transferAmount": {
"type": "number",
"format": "Double",
"description": "Valor total de la transacción.",
"example": 3458.33,
"maxLength": 15
},
"commerceUrl": {
"type": "string",
"description": "Vínculo del comercio al cual se redireccionan los usuarios al finalizar el proceso.",
"example": "https:\/\/gateway.com\/payment\/route?commerce=Telovendo",
"maxLength": 500
},
"confirmationURL": {
"type": "string",
"description": "Vínculo de confirmación para notificarle al comercio que la transacción de compra finalizó (Callback).",
"example": "https:\/\/pagos-api-dev.cloud.net\/callback",
"maxLength": 500
}
}
}
}
}
}
{
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#\/definitions\/meta"
},
"data": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "object",
"required": [
"transferCode",
"redirectURL"
],
"properties": {
"header": {
"$ref": "#\/definitions\/headerData"
},
"transferCode": {
"type": "string",
"description": "Identificador único de la transferencia.",
"example": "ABC123456",
"maxLength": 50
},
"redirectURL": {
"type": "string",
"description": "URL de la pasarela de Botón Bancolombia para continuar con la experiencia de compra.",
"example": "https:\/\/gateway.com\/payment\/route?commerce=Telovendo",
"maxLength": 500
}
}
}
}
}
}
{
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#\/definitions\/meta"
},
"data": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "object",
"required": [
"transferState",
"transferAmount",
"transferReference"
],
"properties": {
"header": {
"$ref": "#\/definitions\/headerData"
},
"transferState": {
"type": "string",
"description": "Estado de la transacción.",
"example": "rejected",
"maxLength": 20,
"enum": [
"approved",
"rejected",
"pending"
]
},
"transferStateDescription": {
"type": "string",
"description": "Descripción del estado de la transacción.",
"example": "La cuenta no tiene saldo suficiente para la transacción",
"maxLength": 255
},
"transferVoucher": {
"type": "string",
"description": "Número de comprobante de la transacción.",
"example": "TRfV3Vitpod5",
"maxLength": 50
},
"transferDate": {
"type": "string",
"format": "date-time",
"description": "Fecha en la que se aprobó o rechazó la transacción.",
"example": "2019-09-16T05:00:00",
"maxLength": 20
},
"transferReference": {
"type": "string",
"description": "Código de referencia de la transacción para el comercio.",
"example": "string",
"maxLength": 100
},
"transferAmount": {
"type": "number",
"format": "Double",
"description": "Valor total de la transacción.",
"example": 10325.55,
"maxLength": 15
}
}
}
}
}
}
El "tipo" y "id" para cada registro.
{
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string",
"example": "Tranference"
},
"id": {
"type": "string"
}
},
"additionalProperties": false
}
Meta-información no estándar que no se puede representar con datos.
{
"type": "object",
"required": [
"_messageId",
"_version",
"_requestDate"
],
"properties": {
"_messageId": {
"type": "string",
"example": "c4e6bd04-5149-11e7-b114-b2f933d5fe66"
},
"_version": {
"type": "string",
"example": "1.0"
},
"_requestDate": {
"type": "string",
"format": "date-time",
"example": "2017-01-24T05:00:00.000Z"
},
"_responseSize": {
"type": "integer",
"example": 1
},
"_clientRequest": {
"type": "string",
"example": "acxff62e-6f12-42de-9012-3e7304418abd"
}
}
}
URLs relacionadas con los datos primarios.
{
"type": "object",
"allOf": [
{
"$ref": "#\/definitions\/links"
}
]
}
Un objeto de recurso PUEDE contener referencias a otros objetos de recurso
{
"type": "object",
"properties": {
"self": {
"description": "Un mismo miembro, cuyo valor es una URL para los datos de relación",
"type": "string",
"format": "uri"
},
"related": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
}
{
"type": "object",
"required": [
"meta",
"errors"
],
"properties": {
"meta": {
"$ref": "#\/definitions\/meta"
},
"errors": {
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#\/definitions\/error"
}
}
},
"additionalProperties": false
}
{
"type": "object",
"required": [
"code",
"detail"
],
"properties": {
"id": {
"description": "Un identificador único para esta aparición particular del problema.",
"type": "string",
"example": "5f2d287a-3a3f-11e7-a919-92ebcb67fe33"
},
"href": {
"description": "Un URI que ** PUEDE ** proporciona más detalles sobre esta ocurrencia particular del problema.",
"type": "string",
"example": "https:\/\/tools.ietf.org\/html\/rfc7231#section-6.5.4"
},
"status": {
"description": "El código de estado HTTP aplicable a este problema, expresado como un valor de cadena.",
"type": "string",
"example": 404
},
"code": {
"description": "Un código de error específico de la aplicación, expresado como un valor de cadena.",
"type": "string",
"example": "BP404"
},
"title": {
"description": "Un breve resumen, legible por el hombre, del problema. ** NO DEBE ** cambiar de ocurrencia a ocurrencia del problema, excepto para propósitos de localización.",
"type": "string",
"example": "Not Found"
},
"detail": {
"description": "Una explicación legible por humanos específica para esta ocurrencia del problema.",
"type": "string",
"example": "Requested resource could not be found"
}
},
"additionalProperties": false
}