Servicios

Todos los consumos se realizan a la URL base, que será proporcionada por el comercio y se le adiciona el endpoint del servicio a consumir

POST/invoice/search/

Búsqueda de facturas

Es el método con el cual se listan las facturas relacionadas con los parametros de consulta descritos a continuación:

Campos con los cuales se realiza la peticion de consulta

Nombre	Tipo	Descripción
`auth`	Autenticación	Información de autenticación.
`agreement`	String	Código de convenio.
`searchType`	String	Nombre del filtro de búsqueda que puede tener uno de los siguientes valores: reference: Busca por la referencia de la factura. document: Busca por el número de documento del pagador. alt_reference: Busca por la referencia alterna posible.
`searchValue`	String	Pago por cuotas con interés.
`siteId`	String	Credencial de identificación del sitio.
`filters (Opcional)`	filters	Estructura que permite extender la búsqueda.
`locale (Opcional)`	Locale	Indica el idioma de la plataforma. Permite dar manejo a traducciones en los Mensajes de error.

Ejemplo de petición

 {
    "auth": {
        "login": "test_user_login",
        "tranKey": "+ZmLlE0ZgHa/C9wxTfDaHHIjb4krPxj/zQzpJsmI81w=",
        "nonce": "TldFeFpqZGpPRE5rTVRNd1pUUTJPREZoTTJNeE1UYzFOekJsWVRVNFl6TT0=",
        "seed": "2025-03-06T10:43:36-05:00"
    },

    "agreement": "1234567",
    "searchType": "reference/alt_reference/document",
    "searchValue": "1040035000",
    "siteId": "657853a1y192317v2k59764fdb547e80"
 }

Ejemplo de respuesta

    
{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-11-13T11:24:27-05:00"
  },
  "data": [
    {
      "id": 4,
      "status": "ACTIVE",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC",
        "name": "Diego",
        "surname": "Perez",
        "email": "[email protected]"
      },
      "payment": {
        "reference": "1234",
        "description": "Testing",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 1900,
              "base": 10000
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 130000
            }
          ],
          "currency": "COP",
          "total": 140000.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "paymentMethod": ["visa", "pse"],
      "altReference": null,
      "createdAt": "2025-10-28T00:00:00-05:00",
      "expirationDate": "2025-11-27T23:59:59-05:00"
    },
    {
      "id": 5,
      "status": "EXPIRED",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC"
      },
      "payment": {
        "reference": "1234",
        "description": "Testing",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 1900
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 130000
            }
          ],
          "currency": "COP",
          "total": 140000.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": null,
      "createdAt": "2025-09-26T00:00:00-05:00",
      "expirationDate": "2025-10-26T23:59:59-05:00"
    },
    {
      "id": 2,
      "status": "EXPIRED",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC"
      },
      "payment": {
        "reference": "1234",
        "description": "Viaje",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 12,
              "base": 90
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 108
            }
          ],
          "currency": "COP",
          "total": 120.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": "9000",
      "createdAt": "2025-04-10T00:00:00-05:00",
      "expirationDate": "2025-05-10T23:59:59-05:00"
    }
  ]
}

filters

Es una estructura que permite extender los parámetros en la búsqueda de facturas. Esta estructura NO sustituye al parámetro “searchType/searchValue”, por ende, si un parámetro ya fue enviado en “searchType/searchValue” no debe ser incluido en la estructura filters. Los siguientes parametros son opcionales:

Nombre	Tipo	Descripción
`reference`	String	Corresponde a la referencia de la factura.
`document`	String	Corresponde al documento del pagador de la factura.
`alt_reference`	String	Corresponde a la referencia alterna de la factura.

Los filters enviados corresponden a los "Campos de acceso” configurados en el micrositio.

Ejemplo


{
  "auth": {
    "login": "test_user_login",
    "tranKey": "+ZmLlE0ZgHa/C9wxTfDaHHIjb4krPxj/zQzpJsmI81w=",
    "nonce": "TldFeFpqZGpPRE5rTVRNd1pUUTJPREZoTTJNeE1UYzFOekJsWVRVNFl6TT0=",
    "seed": "2025-03-06T10:43:36-05:00"
  },
  "agreement": "1234567",
  "searchType": "reference/alt_reference/document",
  "searchValue": "1040035000",
  "siteId": "657853a1y192317v2k59764fdb547e80",
  "filters": {
    "reference": "7890",
    "alt_reference": "788042"
  }
}

Ejemplo de respuesta sin facturas encontradas
El objeto data debe ser un arreglo vacío o un nulo

Ejemplo


{
    "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-11-13T11:24:27-05:00"
 },
 "data": []
}

minAmountToPay & maxAmountToPay

Es una estructura que permite al usuario modificar el monto total a pagar, ya sea por un monto menor o un monto mayor, para esto es necesario incluir la llave minAmountToPay y maxAmountToPay

Ejemplo


{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-06-22T11:24:27-05:00"
  },
  "data": [
    {
      "id": 4,
      "status": "ACTIVE",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC",
        "name": "Diego",
        "surname": "Perez",
        "email": "[email protected]"
      },
      "payment": {
        "reference": "1234",
        "description": "Testing",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 1900,
              "base": 10000
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 130000
            }
          ],
          "currency": "COP",
          "total": 140000.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": null,
      "createdAt": "2025-06-10T00:00:00-05:00",
      "expirationDate": "2025-07-27T23:59:59-05:00",
      "minAmountToPay": 50000,
      "maxAmountToPay": 140000
    },
    {
      "id": 2,
      "status": "ACTIVE",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC"
      },
      "payment": {
        "reference": "1234",
        "description": "Viaje",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 12,
              "base": 90
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 108
            }
          ],
          "currency": "COP",
          "total": 120.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": "9000",
      "createdAt": "2025-05-22T00:00:00-05:00",
      "expirationDate": "2025-07-22T23:59:59-05:00",
      "minAmountToPay": 40,
      "maxAmountToPay": 120
    }
  ]
}

Ejemplo de respuesta cuando se va a permitir la modificación del monto máximo a pagar de las facturas
Este escenario, donde se puede modificar el monto máximo a pagar, lo podemos ver como por ejemplo:

Diferir la deuda en cuotas:
- Valor Total: $ 1.200.000
- Cuota mensual: $ 100.000
- Cuotas: 12
- El deudor, podria decidir pagar el total de la deuda en el pago #6, por lo cual tendriamos:

Ejemplo


    {
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-06-22T11:24:27-05:00"
  },
  "data": [
    {
      "id": 4,
      "status": "ACTIVE",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC",
        "name": "Diego",
        "surname": "Perez",
        "email": "[email protected]"
      },
      "payment": {
        "reference": "1234",
        "description": "Testing",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 0,
              "base": 0
            }
          ],
          "currency": "COP",
          "total": 1000000.0
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": null,
      "createdAt": "2025-06-10T00:00:00-05:00",
      "expirationDate": "2025-07-27T23:59:59-05:00",
      "minAmountToPay": 100000.00,
      "maxAmountToPay": 1200000.00
    }
  ]
}

La gestión del monto pendiente de pagar se debe gestionar por parte del proveedor de las facturas.

Fusionar medios de pago

El campo mergePaymentMethods dentro de la estructura options es el que permite definir el comportamiento esperado en este caso, para saber mas información acerca de este campo por favor dirigirse al siguiente apartado mergePaymentMethods

Ejemplo

{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-06-22T11:24:27-05:00"
  },
  "data": [
    {
      "id": 1,
      "status": "ACTIVE",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC",
        "name": "Diego",
        "surname": "Perez",
        "email": "[email protected]"
      },
      "payment": {
        "reference": "1234",
        "description": "Testing",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 1900,
              "base": 10000
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 130000
            }
          ],
          "currency": "COP",
          "total": 140000.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": null,
      "paymentMethod": ["pse", "amex"],
      "createdAt": "2025-06-10T00:00:00-05:00",
      "expirationDate": "2025-07-27T23:59:59-05:00"
    },
    {
      "id": 2,
      "status": "ACTIVE",
      "debtor": {
        "document": "1040035000",
        "documentType": "CC"
      },
      "payment": {
        "reference": "1234",
        "description": "Viaje",
        "amount": {
          "taxes": [
            {
              "kind": "valueAddedTax",
              "amount": 12,
              "base": 90
            }
          ],
          "details": [
            {
              "kind": "subtotal",
              "amount": 108
            }
          ],
          "currency": "COP",
          "total": 120.00
        },
        "allowPartial": false,
        "subscribe": false
      },
      "altReference": "9000",
      "paymentMethod": ["amex", "pse"],
      "createdAt": "2025-05-22T00:00:00-05:00",
      "expirationDate": "2025-07-22T23:59:59-05:00"
    }
  ],
  "options": {
    "mergePaymentMethods": true
  }
}

POST/invoice/hold

Bloqueo y liberación de facturas

Es el método con el cual se bloquea y se libera la factura dependiendo del comportamiento deseado.

Nombre	Tipo	Descripción
`auth`	Autenticación	Información de autenticación.
`id`	Int	Identificador de la factura (id).
`reference`	String	Referencia de la factura.
`revoke`	Bool	Determina si se debe revocar el hold o no false: La factura quedará bloqueada true: La factura será liberada.
`siteId`	String	Credencial de identificación del sitio
`locale`	locale	Indica el idioma de la plataforma. Permite dar manejo a traducciones en los Mensajes de error.

Ejemplo de petición para bloquear factura.
El campo revoke en este caso siempre debe ser false.

Ejemplo bloquear factura


{
    "auth": {
    "login": "dnix",
    "tranKey": "z1NGjj551My0JkNvYXU\/2B4T3tgBB43Ek3UFDwqTx\/Y=",
    "nonce": "MTE5ODE0",
    "seed": "2025-03-20T08:53:42-05:00"
  },
    "id": 8777,
    "reference": "6313",
    "revoke": false,
    "siteId": "657853a1y192317v2k59764fdb547e80"
}

Ejemplo de respuesta de factura bloqueada.

En este caso el estado de la factura debe ser HOLD con el objetivo que Micrositios no permita realizar un pago de la misma factura mientras ésta no sea liberada.

Ejemplo factura bloqueada

{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-03-20T10:45:33-05:00"
  },
  "data": {
    "id": 6,
    "status": "HOLD",
    "debtor": {
      "document": "1040035000",
      "documentType": "CC"
    },
    "payment": {
      "reference": "20328",
      "description": "123",
      "amount": {
        "taxes": [
          {
            "kind": "valueAddedTax",
            "amount": 1000,
            "base": 0
          }
        ],
        "details": [
          {
            "kind": "subtotal",
            "amount": 99000
          }
        ],
        "currency": "COP",
        "total": 100000.00
      },
      "allowPartial": false,
      "shipping": null,
      "items": null,
      "recurring": null,
      "subscribe": false,
      "fields": null,
      "agreement": null,
      "agreementType": null,
      "gds": null
    },
    "altReference": null,
    "createdAt": "2025-03-20",
    "expirationDate": "2025-04-19 23:59:59",
    "finalDate": "2025-04-19 23:59:59",
    "siteId": 1
  }
}

Ejemplo de petición para liberar factura.

El campo revoke en este caso siempre debe ser true

Ejemplo bloquear factura


{
  "auth": {
  "login": "dnix",
  "tranKey": "z1NGjj551My0JkNvYXU\/2B4T3tgBB43Ek3UFDwqTx\/Y=",
  "nonce": "MTE5ODE0",
  "seed": "2025-03-20T08:53:42-05:00"
  },
  "id": 8777,
  "reference": "6313ccx",
  "invoice": 6,
  "revoke": true,
  "siteId": "657853a1y192317v2k59764fdb547e80"
}

Ejemplo de respuesta de factura liberada.

En este caso el estado de la factura debe ser distinto de ACTIVE.

Ejemplo factura liberada


{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-03-20T10:45:33-05:00"
  },
  "data": {
    "id": 6,
    "status": "ACTIVE",
    "debtor": {
      "document": "1040035000",
      "documentType": "CC"
    },
    "payment": {
      "reference": "20328",
      "description": "123",
      "amount": {
        "taxes": [
          {
            "kind": "valueAddedTax",
            "amount": 1000,
            "base": 0
          }
        ],
        "details": [
          {
            "kind": "subtotal",
            "amount": 99000
          }
        ],
        "currency": "COP",
        "total": 100000.00
      },
      "allowPartial": false,
      "shipping": null,
      "items": null,
      "recurring": null,
      "subscribe": false,
      "fields": null,
      "agreement": null,
      "agreementType": null,
      "gds": null
    },
    "altReference": null,
    "createdAt": "2025-03-20",
    "expirationDate": "2025-04-19 23:59:59",
    "finalDate": "2025-04-19 23:59:59",
    "siteId": 1
  }
}

POST/invoice/settle/

Asentamiento de factura

Es el método realiza el asentamiento de la factura en el servicio del comercio, se realiza con los siguientes campos:

Nombre	Tipo	Descripción
`auth`	Autenticación	Información de autenticación.
`locale`	locale	Indica el idioma de la plataforma. Permite dar manejo a traducciones en los Mensajes de error.
`id`	Int	Identificador de la factura (id).
`reference`	String	Referencia de la factura.
`agreement`	String	Código de convenio.
`authorization`	String	Monto pagado.
`amount`	String	Código de convenio.
`date`	String	Fecha de pago.
`paymentMethod`	String	Metodo de pago usado.
`receipt`	String	Código de recibo proporcionado por la red.
`franchise`	String	Codigo de la franquicia utilizado.
`franchiseName`	String	Nombre de la franquicia utilizado.
`internalReference`	String	Identificador de la transacción en PlacetoPay.
`siteId`	String	Credencial de identificación del sitio
`channel`	String	Canal por el cual se realizó el recaudo: OFC = Oficina. ATM = Cajero electrónico. IVR = Sistema audio respuesta. DEB = Débito automático. MOV = Banca móvil. WEB = Portal Web.
`requestId`	Int	Identificador de la sesión de pago en Web Checkout. Este parámetro permite consultar el estado del pago a través de un medio disponible
`issuerName`	String	Nombre del banco emisor del pago.
`lastDigits`	String	Últimos 4 digitos de la tarjeta con la que se realizo el pago.
`provider`	String	Se envia el string "provider".
`method`	String	Código del medio de pago.

Ejemplo de petición

 {
    "auth": {
      "login": "test_user_login",
      "tranKey": "dsRL5wIymrySr9TgsYtxWZEIb5/RtW1v3n3xLqQZKj4=",
      "nonce": "MTIzNDU2Nzg=",
      "seed": "2025-03-06T10:44:49-05:00"
  },
    "id": 1,
    "reference": "12345",
    "agreement": "1234567",
    "authorization": "8785757",
    "receipt": "000000",
    "franchise": "_PSE_",
    "internalReference": 150324,
      "amount": {
      "currency": "COP",
      "total": 108900
    },
    "date": "2025-10-24T11:48:35-05:00",
    "channel": "OFC",
    "paymentMethod": "pse",
    "location": "point_1",
    "siteId": "657853a1y192317v2k59764fdb547e80",
    "requestId": 4018,
 }

Para evitar un doble asentamiento en el sistema del comercio, se debe retornar la siguiente estructura a Placetopay.

Ejemplo de respuesta

{
  "status": {
  "status": "OK",
  "reason": "00",
  "message": "La petición se ha procesado correctamente",
  "date": "2025-11-13T11:30:37-05:00"
  },
 "receipt": 1511
}