--- swagger: "2.0" info: title: Bancolombia Button - Transference Management description: |-

Botón Bancolombia ofrece varias funcionalidades que permiten a los comercios procesar transacciones y conocer su estado en línea


Funcionalidades


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.


Importante: Todos los campos se envían como String pero se respeta el tipo de dato que se muestra a continuación:


Campos que se envían en el Callback


Campo Tipo Longitud máxima Descripción
transferVoucher String 50 Número de comprobante de la transacción.
transferAmount Double 15 Monto de la transacción
transferStateDescription String 225 Descripción del resultado de la transacción
sign String 128 Firma que permitirá validar la integridad del request generado por Bancolombia
requestDate DateTime 23 Fecha en la que se registró la orden
transferState String 20 Estado de la transacción
transferDate Date 20 Fecha en la que se aprobó o rechazó la transacción.
transferCode String 50 Identificador único de la transferencia
transferReference String 48 Código de referencia de la transacción para el comercio.
commerceTransferButtonId String 50 HASH que identifica el Botón Bancolombia del comercio

¿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

contact: name: Bancolombia API Working Group email: apigroup@bancolombia.com.co url: https://developer.bancolombia.com/contact version: 2.0.4 x-ibm-name: bancolombia-button-transference-management basePath: /v2/operations/cross-product/payments/payment-order paths: /transfer/action/registry: post: summary: Registrar intención de compra. description: 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. parameters: - name: reqTransferencesRegistry required: true in: body description: Datos necesarios para registrar la intención de compra. schema: $ref: '#/definitions/reqTransferRegistry' responses: 200: schema: $ref: '#/definitions/resTransferRegistry' description: Respuesta exitosa. x-ibm-languages: description: en: Successful response. headers: X-API-Version: type: number format: float description: Versionamiento semantico de la API x-ibm-languages: description: en: Semantic versioning of the API X-RateLimit-Limit: type: integer description: Límite de solicitudes por hora x-ibm-languages: description: en: Resquest limit per hour. 400: schema: $ref: '#/definitions/failure' description: Error en la solicitud. x-ibm-languages: description: en: Error in the request. 401: schema: $ref: '#/definitions/failure' description: Credenciales incorrectas. x-ibm-languages: description: en: Incorrect credentials. 403: schema: $ref: '#/definitions/failure' description: No tiene permisos para acceder al recurso. x-ibm-languages: description: en: You do not have permissions to access the resource. 404: schema: $ref: '#/definitions/failure' description: Recurso no encontrado. x-ibm-languages: description: en: Resource not found. 409: schema: $ref: '#/definitions/failure' description: El estado del recurso presenta conflictos con los datos de la solicitud. x-ibm-languages: description: en: Resource state has conflicts with data of the request. 500: schema: $ref: '#/definitions/failure' description: Error interno del servidor. x-ibm-languages: description: en: Internal server error. 502: schema: $ref: '#/definitions/failure' description: Error en la respuesta del proveedor del servicio. x-ibm-languages: description: en: Error in the service provider response. 503: schema: $ref: '#/definitions/failure' description: Servicio no disponible. x-ibm-languages: description: en: Service unavailable. 504: schema: $ref: '#/definitions/failure' description: Tiempo de respuesta del proveedor del servicio excedido. x-ibm-languages: description: en: Service provider response time exceeded. tags: - Button security: - OAuth - Provider from OTP Pymes - Flow Application: - Transfer-Intention:write:app /transfer/{transferCode}/action/validate: get: summary: Consultar el estado de una transferencia. description: El API de Consultar Transferencia tiene como funcionalidad consultar el estado de la transacción. parameters: - name: transferCode type: string required: true in: path description: Identificador único de la transferencia. responses: 200: schema: $ref: '#/definitions/resTransfer' description: Respuesta exitosa. x-ibm-languages: description: en: Successful response. headers: X-API-Version: type: number format: float description: Versionamiento semantico de la API x-ibm-languages: description: en: Semantic versioning of the API X-RateLimit-Limit: type: integer description: Límite de solicitudes por hora x-ibm-languages: description: en: Resquest limit per hour. 400: schema: $ref: '#/definitions/failure' description: Error en la solicitud. x-ibm-languages: description: en: Error in the request. 401: schema: $ref: '#/definitions/failure' description: Credenciales incorrectas. x-ibm-languages: description: en: Incorrect credentials. 403: schema: $ref: '#/definitions/failure' description: No tiene permisos para acceder al recurso. x-ibm-languages: description: en: You do not have permissions to access the resource. 404: schema: $ref: '#/definitions/failure' description: Recurso no encontrado. x-ibm-languages: description: en: Resource not found. 409: schema: $ref: '#/definitions/failure' description: El estado del recurso presenta conflictos con los datos de la solicitud. x-ibm-languages: description: en: Resource state has conflicts with data of the request. 500: schema: $ref: '#/definitions/failure' description: Error interno del servidor. x-ibm-languages: description: en: Internal server error. 502: schema: $ref: '#/definitions/failure' description: Error en la respuesta del proveedor del servicio. x-ibm-languages: description: en: Error in the service provider response. 503: schema: $ref: '#/definitions/failure' description: Servicio no disponible. x-ibm-languages: description: en: Service unavailable. 504: schema: $ref: '#/definitions/failure' description: Tiempo de respuesta del proveedor del servicio excedido. x-ibm-languages: description: en: Service provider response time exceeded. tags: - Button security: - OAuth - Provider from OTP Pymes - Flow Application: - Transfer-Intention:read:app /bancolombia-button-transference-management/health: head: description: Operación de monitoreo para la api summary: Operación de monitoreo responses: 200: description: Respuesta exitosa. x-ibm-languages: description: en: Successful response. tags: - Monitoring security: - OAuth - Provider from OTP Pymes - Flow Application: - Transfer-Intention:write:app - Transfer-Intention:read:app definitions: reqTransferRegistry: type: object required: - data properties: data: type: array items: type: object required: - commerceTransferButtonId - transferReference - transferAmount - commerceUrl properties: commerceTransferButtonId: type: string description: HASH que identifica el botón de transferencia del comercio. example: w0mp1B0toN 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.330000 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.tigocloud.net/bancolombia/callback maxLength: 500 resTransferRegistry: 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 resTransfer: 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.550000 maxLength: 15 headerData: description: El "tipo" y "id" para cada registro. type: object required: - type - id properties: type: type: string example: Tranference id: type: string additionalProperties: false meta: description: 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 failure: type: object required: - meta - errors properties: meta: $ref: '#/definitions/meta' errors: type: array uniqueItems: true items: $ref: '#/definitions/error' additionalProperties: false error: 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 schemes: - https consumes: - application/json - application/vnd.bancolombia.v1+json produces: - application/json - application/vnd.bancolombia.v1+json tags: - name: Button description: Operaciones sobre un Boton Bancolombia - name: Monitoring description: Operaciones para realizar el monitoreo de la API x-ibm-configuration: enforced: true testable: true phase: specified securityDefinitions: OAuth - Provider from OTP Pymes - Flow Application: type: oauth2 description: Proveedor de OAuth para autenticación con One Time Password(OTP) para Pymes flow: application 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 tokenUrl: https://api.us.apiconnect.ibmcloud.com/bancolombiabluemix-dev/sandbox/v1/security/oauth-otp-pymes/oauth2/token x-tokenIntrospect: url: "" x-API-Protocol: Protocols: HTTPS x-ibm-endpoints: - endpointUrl: https://sbapi.bancolombia.com description: Base Gateway API Endpoint type: - production - development ...