Links de pago

Un link de pago es una URL que permite a los usuarios completar un pago de forma rápida y fácil. Puede ser compartido por correo, redes sociales o mensajes de texto.

POST/api/payment-link

Crear un link

Este endpoint permite crear un link de pago y configurarlo de acuerdo a tus necesidades

Solicitud

Name
auth
Type
object
is Required
REQUIRED
Description
La autenticación del sitio. Ver más en Autenticación
Name
login
Type
string
is Required
REQUIRED
Description
Identificador del sitio
Name
tranKey
Type
string
is Required
REQUIRED
Description
Credencial tranKey generado
Name
nonce
Type
string
is Required
REQUIRED
Description
Valor aleatorio para cada solicitud codificado en Base64.
Name
seed
Type
string
is Required
REQUIRED
Description
Fecha actual, la cual se genera en formato ISO 8601.
Name
notificationUrl
Type
string
is optional
Description
URL a la que se enviarán las notificaciones de los pagos realizados a través del link de pago, así como las notificaciones de expiración del link. Para más detalles, visita Notificación.

EJ: https://webhook-test.com
Name
locale
Type
string
is optional
Description
Idioma en que sera enviado y se mostrara el link de pago, visita Localización para conocer sus valores permitidos

EJ: es_CO
Valores permitidos:enesptitfr
Name
name
Type
string
is Required
REQUIRED
Description
Nombre que será asociado al link de pago.

EJ: my-product-name
Name
paymentsAllowed
Type
integer
is optional
Description
Número de pagos que se podrán realizar a través del link. Si este campo no se envía, el link permitirá una cantidad ilimitada de pagos..

EJ: 7
Name
expirationDate
Type
string
is Required
REQUIRED
Description
Fecha y hora en la que el link dejará de estar activo. La fecha debe ser posterior a la fecha y hora actual del usuario.

EJ: 2023-10-21 16:40:10
Name
paymentExpiration
Type
integer
is Required
REQUIRED
Description
Cantidad de tiempo en minutos permitido para completar cada sesión de Checkout.

EJ: 15
Name
payment
Type
object
is Required
REQUIRED
Description
Información del pago que se realizará a través del link de pago.
Name
amount
Type
object
is optional
Description
Información del monto a cobrar a través del link de pago.
Name
currency
Type
string
is optional
Description
Moneda en la que se realizará el cobro a través del link de pago.

EJ: USD
Name
total
Type
integer
is optional
Description
Monto total que tendrá el pago que se realizará a través del link.

EJ: 100
Name
taxes
Type
array
is optional
Description
Estructura para definir impuestos en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de impuesto

Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Valores permitidos:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Ejemplo:valueAddedTax
Name
amount
Type
number
is optional
Description
Monto total del impuesto
EJ: 200
Name
base
Type
number
is optional
Description
Monto base sobre el cual se calcula el impuesto
EJ: 1000
Name
modifiers
Type
array
is optional
Description
Estructura para definir modificadores en el cobro. Aplica para leyes de impuestos en paises especificos.
Name
type
Type
string
is optional
Description
Identificador del tipo de modificador.
Sólo FEDERAL_GOVERMENT es soportado actualmente.
Valores permitidos:FEDERAL_GOVERNMENT
Ejemplo:FEDERAL_GOVERNMENT
Name
code
Type
number
is optional
Description
Código del modificador.

Para FEDERAL_GOVERMENT representa el número de ley para descuento.
17934 Servicios Gastronómicos
18083 IMESI Brasil - Argentina
19210 Inclusión Financiera
18910 Asignaciones Familiares
18999 Reintegro Inmobiliarias
Valores permitidos:1793418083192101891018999
Ejemplo:17934
Name
additional
Type
object
is optional
Description
Estructura para anexar información al modificador
Name
invoice
Type
string
is optional
Description
Requerido cuando modifiers.[n].type es FEDERAL_GOVERMENT. Indica el número de factura. maxLength: 9 example: '123456789'
Name
reference
Type
string
is Required
REQUIRED
Description
Referencia única asociada al link de pago.

EJ: Reference123
Name
description
Type
string
is Required
REQUIRED
Description
Descripción asociada al link de pago.

EJ: Descripción de mi producto
Name
paymentMethod
Type
array
is optional
Description
Métodos de pago permitidos para usar en el link de pago creado. Solo se pueden enviar métodos de pago que estén habilitados en tu sitio.

EJ: ["pse", "visa", "master"]
Name
receiverEmails
Type
array
is optional
Description
Lista de correos electrónicos a los que se enviará el link una vez que se haya creado correctamente.

EJ: ["[email protected]", "[email protected]"]
Name
additional
Type
object
is optional
Description
Campos adicionales para el link de pago. algunos campos de adicionales que podrias utilizar son:
Name
buyer_email
Type
email
is optional
Description
Correo electrónico del comprador.
Name
buyer_name
Type
string
is optional
Description
Nombre del comprador.

Solicitud

POST

/api/payment-link

curl -X "POST"	https://sites.placetopay.com/api/payment-link \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login":"c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    },
    "notificationUrl": "https://webhook-test.com",
    "locale": "es_CO",
    "name": "Prueba",
    "paymentsAllowed": 7,
    "expirationDate": "2024-08-12 08:10:50",
    "paymentExpiration": 15,
    "payment": {
        "amount": {
            "currency": "COP",
            "total": 100000,
            "taxes": [
                {
                    "kind": "valueAddedTax",
                    "amount": 20000,
                    "base": 1000
                },
                {
                    "kind": "municipalTax",
                    "amount": 5000,
                    "base": 2000
                }
            ]
        },
        "modifiers": [
            {
                "type": "FEDERAL_GOVERNMENT",
                "code": 17934,
                "additional": {
                    "invoice": "12334577"
                }
            }
        ]
    },
    "reference": "#5321",
    "description": "Pago por infraccion",
    "paymentMethod": ["pse", "visa"],
    "receiverEmails": ["[email protected]", "[email protected]"],
    "additional": {
        "buyer_email": "[email protected]",
        "buyer_name": "Billy"
    }
}'

Respuesta

Link de pago creado correctamente

Name
status
Type
object
is Required
REQUIRED
Description
Objeto status contiene la información del estado de la solicitud
Name
status
Type
string
is Required
REQUIRED
Description
Estado de la solicitud
Name
reason
Type
integer
is Required
REQUIRED
Description
Código de respuesta
Name
message
Type
string
is Required
REQUIRED
Description
Mensaje de respuesta
Name
date
Type
string
is Required
REQUIRED
Description
Fecha y hora de la respuesta
Name
id
Type
integer
is optional
Description
ID único e incremental del link de pago creado, este ID es el que se usará para consultar la información del link de pago.

EJ: 1
Name
url
Type
string
is optional
Description
URL del link de pago. Esta URL es la que se debe enviar al comprador para que pueda realizar el pago.

EJ: http://microsites.test/link/show?genid=27&code=47

Respuesta

{
    "status": {
        "status": "OK",
        "reason": 201,
        "message": "Link de pago creado y correos electrónicos enviados correctamente.",
        "date": "2024-07-31T11:36:23-05:00"
    },
    "id": 1,
    "url": "http://microsites.test/link/show?genid=22&code=190"
}

POST/api/payment-link/{link_id}

Consultar un link

Este endpoint permite consultar un link de pago y obtener información detallada sobre el mismo. Si el link contiene pagos, también se mostrarán en la respuesta.

Solicitud

Name
auth
Type
object
is Required
REQUIRED
Description
El objeto auth es obligatorio para lograr conectarse de forma segura a nuestros servicios
Name
login
Type
string
is Required
REQUIRED
Description
Identificador del sitio
Name
tranKey
Type
string
is Required
REQUIRED
Description
Credencial tranKey generado
Name
nonce
Type
string
is Required
REQUIRED
Description
Valor aleatorio para cada solicitud codificado en Base64.
Name
seed
Type
string
is Required
REQUIRED
Description
Fecha actual, la cual se genera en formato ISO 8601.

Solicitud

POST

/api/payment-link/{link_id}

curl -X "POST" https://sites.placetopay.com/api/payment-link/{link_id}\
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login":"c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    }
}'

Respuesta

Link de pago consultado correctamente

Name
id
Type
integer
is Required
REQUIRED
Description
ID del link consultado.

EJ: 21
Name
status
Type
string
is Required
REQUIRED
Description
Estado del link consultado.

EJ: ACTIVE
Valores permitidos:ACTIVEINACTIVEEXPIRED
Name
url
Type
string
is Required
REQUIRED
Description
URL del link consultado.

EJ: http://microsites.test/link/show?genid=26&code=47
Name
expirationDate
Type
string
is optional
Description
Fecha y hora de expiración del link consultado en formato UTC.

EJ: 2024-08-12T08:10:50-05:00
Name
name
Type
string
is Required
REQUIRED
Description
Nombre asociado al link consultado.

EJ: Prueba
Name
reference
Type
string
is Required
REQUIRED
Description
Referencia asociada al link consultado.

EJ: #5321
Name
description
Type
string
is Required
REQUIRED
Description
Descripción asociada al link de pago.

EJ: Descripción de un link de pago
Name
totalPayments
Type
integer
is optional
Description
Cantidad de pagos permitidos a través del link consultado.

EJ: 7
Name
availablePayments
Type
integer
is optional
Description
Cantidad de pagos disponibles en el link consultado.

EJ: 6
Name
paymentExpiration
Type
integer
is optional
Description
Minutos que dura una sesión de pago antes de expirar.

EJ: 15
Name
amount
Type
integer
is Required
REQUIRED
Description
Información del monto a cobrar a través del link de pago
Name
currency
Type
string
is optional
Description
Moneda en la que se realizará el cobro a través del link de pago.

EJ: USD
Name
total
Type
integer
is optional
Description
Monto total que tendrá el pago que se realizará a través del link.

EJ: 100
Name
taxes
Type
array
is optional
Description
Estructura para definir impuestos en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de impuesto

Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Valores permitidos:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Ejemplo:valueAddedTax
Name
amount
Type
number
is optional
Description
Monto total del impuesto
EJ: 200
Name
base
Type
number
is optional
Description
Monto base sobre el cual se calcula el impuesto
EJ: 1000
Name
site
Type
object
is Required
REQUIRED
Description
Información del sitio asociado al link de pago.
Name
id
Type
integer
is Required
REQUIRED
Description
ID del sitio al que está asociado el link de pago.

EJ: 112
Name
name
Type
string
is Required
REQUIRED
Description
Nombre del sitio asociado.

EJ: Ebus PFKR 2
Name
metadata
Type
object
is optional
Description
Información adicional asociada al link de pago.

EJ: {"discount":[{"code":17934,"type":"FEDERAL_GOVERNMENT","additional":{"invoice":"123456777"}}]}
Name
payments
Type
array
is optional
Description
Lista que contiene todos los pagos realizados a través del link. Si no se ha realizado ningún pago, este campo se mostrará como un array vacío.
Name
id
Type
integer
is optional
Description
ID del pago realizado.

EJ: 22
Name
requestId
Type
integer
is optional
Description
RequestId de la sesión de Checkout en la que se realizó el pago.

EJ: 84076
Name
status
Type
string
is optional
Description
Estado de la transacción realizada.

EJ: APPROVED
Name
message
Type
string
is optional
Description
Mensaje del estado de la transacción.

EJ: La petición ha sido aprobada exitosamente
Name
proccessUrl
Type
string
is optional
Description
URL de la sesión de pago en la que se realizó la transacción.

EJ: https://checkout-co.placetopay.dev/spa/session/80108/f19f30
Name
amount
Type
object
is optional
Description
Name
currency
Type
string
is optional
Description
Moneda en la que se realizó el cobro de la transacción.

EJ: USD
Name
total
Type
string
is optional
Description
Monto total que se cobró en la transacción.

EJ: 100
Name
receipt
Type
string
is optional
Description
Número de recibo de la transacción.

EJ: 241516
Name
franchise
Type
string
is optional
Description
Franquicia de la tarjeta con la que se realizó la transacción.

EJ: DF_VS
Name
paymentMethod
Type
string
is optional
Description
Método de pago con el que se realizó la transacción.

EJ: visa
Name
paymentDate
Type
string
is optional
Description
Fecha y hora en la que se realizó la transacción.

EJ: 2023-10-27T10:39:47-05:00
Name
internalReference
Type
integer
is optional
Description
Referencia interna de la transacción.

EJ: 1
Name
authorization
Type
string
is optional
Description
Número de autorización de la transacción.

EJ: 000000
Name
issuerName
Type
string
is optional
Description
Nombre del banco emisor de la tarjeta con la que se realizó la transacción.

EJ: JPMORGAN CHASE BANK, N.A.
Name
merchantCode
Type
string
is optional
Description
Código del comercio

EJ: 123456
Name
terminalNumber
Type
string
is optional
Description
Número de terminal

EJ: 123456
Name
installments
Type
integer
is optional
Description
Número de cuotas

EJ: 1
Name
lastDigits
Type
string
is optional
Description
Últimos dígitos de la tarjeta

EJ: 1111
Name
payer
Type
object
is optional
Description
Información del pagador que realizó la transacción.
Name
name
Type
string
is optional
Description
Nombre del pagador.

Ej: Andres
Name
surname
Type
string
is optional
Description
Apellido del pagador.

EJ: Zea
Name
email
Type
string
is optional
Description
Email del pagador.

EJ: [email protected]
Name
phone
Type
string
is optional
Description
Teléfono del pagador.

EJ: +1 123123123
Name
document
Type
string
is optional
Description
Documento de identidad del pagador.

EJ: 123456789
Name
documentType
Type
string
is optional
Description
Tipo de documento de identidad del pagador.

EJ: CC

Respuesta

{
    "id": 21,
    "status": "ACTIVE",
    "url": "http://microsites.test/link/show?genid=21&code=ce350a956700cee9e29446a552201ddd55c6a477",
    "expirationDate": "2024-08-12 08:10:50",
    "name": "Prueba",
    "reference": "#5321",
    "description": "Pago por infraccion",
    "totalPayments": 7,
    "availablePayments": 6,
    "paymentExpiration": 15,
    "amount": {
      "currency": "COP",
      "total": 100000,
      "taxes": [
        {
          "base": 80000,
          "kind": "valueAddedTax",
          "amount": 20000
        },
        {
          "base": 50000,
          "kind": "municipalTax",
          "amount": 5000
        }
      ]
    },
    "site": {
        "id": 1469,
        "name": "Evertec - API Link de pagos"
    },
    "notificationUrl": "https://webhook-test.com/dc45064451b3b0fdc61d8d5be632d450",
    "locale": "es_CO",
    "allowedPaymentMethods": [
        "pse",
        "visa"
    ],
    "metadata": {
      "discount": [
        {
          "code": 17934,
          "type": "FEDERAL_GOVERNMENT",
          "additional": {
            "invoice": "123456777"
          }
        }
      ]
    },
    "payments": [
      {
        "id": 8,
        "requestId": 84076,
        "status": "APPROVED",
        "message": "La petición ha sido aprobada exitosamente",
        "processUrl": "https://checkout-co.placetopay.dev/spa/session/84076/79e4267e26771ed8ecffdab18d4c5f69",
        "amount": {
          "currency": "COP",
          "total": "100000.00"
        },
        "receipt": "99900100",
        "franchise": "CR_VS",
        "paymentMethod": "visa",
        "paymentDate": "2024-07-26 08:21:40",
        "internalReference": 434915,
        "authorization": "000000",
        "issuerName": "JPMORGAN CHASE BANK, N.A.",
        "merchantCode": "012988341",
        "terminalNumber": "00022645",
        "installments": 1,
        "lastDigits": "1111",
        "payer": {
          "name": "Andres",
          "surname": "Zea",
          "email": "[email protected]",
          "phone": "+573135911356",
          "document": "1001221123",
          "documentType": "CC"
        }
      }
    ]
}

POST/api/payment-link/disable/{link_id}

Deshabilitar un link

Este endpoint permite desactivar un link de pago lo que impedira que se realicen mas pagos a traves de el

Solicitud

Name
auth
Type
object
is Required
REQUIRED
Description
El objeto auth es obligatorio para lograr conectarse de forma segura a nuestros servicios
Name
login
Type
string
is Required
REQUIRED
Description
Identificador del sitio
Ejemplo:1441d14df19ec88431e513bb990326e1
Name
tranKey
Type
string
is Required
REQUIRED
Description
Credencial tranKey generado
Ejemplo:DGYymv6ohpYwtLWon/iADE/COoo9JXt4jqyk6D006PY=
Name
nonce
Type
string
is Required
REQUIRED
Description
Valor aleatorio para cada solicitud codificado en Base64.
Ejemplo:enQ4dXh3YWhkMWM=
Name
seed
Type
string
is Required
REQUIRED
Description
Fecha actual, la cual se genera en formato ISO 8601.
Ejemplo:2023-06-21T09:56:06-05:00

Solicitud

POST

/api/payment-link/disalbe/{link_id}

curl -X "POST" https://sites.placetopay.com/api/payment-link/disalbe/{link_id} \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login":"c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    }
}'

Respuesta

Link de pago desactivado exitosamente

Name
status
Type
object
is Required
REQUIRED
Description
Objeto status contiene la información del estado de la solicitud
Name
status
Type
string
is Required
REQUIRED
Description
Estado de la solicitud
Name
reason
Type
integer
is Required
REQUIRED
Description
Código de respuesta
Name
message
Type
string
is Required
REQUIRED
Description
Mensaje de respuesta
Name
date
Type
string
is Required
REQUIRED
Description
Fecha y hora de la respuesta
Name
id
Type
string
is Required
REQUIRED
Description
ID del link que ha sido desactivado.

Respuesta

{
    "status": {
        "status": "OK",
        "reason": 200,
        "message": "Link de pago desactivado correctamente.",
        "date": "2024-07-31T14:19:22-05:00"
    },
    "id": 24
}