Payment links

A payment link is a URL that allows users to complete a payment quickly and easily. It can be shared via email, social media, or text message.

POST/api/payment-link

Create a link

This endpoint allows you to create a payment link and configure it according to your needs.

Request

Name
auth
Type
object
is Required
REQUIRED
Description
Site authentication. See more in Authentication
Name
notificationUrl
Type
string
is optional
Description
URL to which notifications of payments made through the payment link will be sent, as well as link expiration notifications. For more details, visit Notification.

EX: https://webhook-test.com
Name
locale
Type
string
is optional
Description
Language in which the payment link will be sent and displayed, visit Localization for its allowed values

EX: es_CO, en_US
Name
name
Type
string
is Required
REQUIRED
Description
Name that will be associated with the payment link.

EX: my-product-name
Name
paymentsAllowed
Type
integer
is optional
Description
Number of payments that can be made through the link. If this field is not sent, the link will allow an unlimited number of payments.

EX: 7
Name
expirationDate
Type
string
is Required
REQUIRED
Description
Date and time when the link will no longer be active. The date must be later than the current user's date and time.

EX: 2023-10-21 16:40:10
Name
paymentExpiration
Type
integer
is Required
REQUIRED
Description
Amount of time in minutes allowed to complete each Checkout session.

EX: 15
Name
payment
Type
object
is Required
REQUIRED
Description
Information about the payment to be made through the payment link.
Name
reference
Type
string
is Required
REQUIRED
Description
Unique reference associated with the payment link.

EX: Reference123
Name
description
Type
string
is Required
REQUIRED
Description
Description associated with the payment link.

EX: Description of my product
Name
paymentMethod
Type
array
is optional
Description
Payment methods allowed to use in the created payment link. Only payment methods enabled on your site can be sent.

EX: ["pse", "visa", "master"]
Name
receiverEmails
Type
array
is optional
Description
List of email addresses to which the link will be sent once it has been successfully created.

EX: ["[email protected]", "[email protected]"]
Name
additional
Type
object
is optional
Description
Additional fields for the payment link. Each field must be unique within the same payment link. For more details, visit NameValuePair.
Name
isGeneric
Type
boolean
is optional
Description
Allows the user to pay multiple times using the same link as long as the total limit of approved payments paymentsAllowed is not exceeded.
Default value:false

Solicitud

POST

/api/payment-link

curl -X "POST" https://sites.placetopay.com/api/payment-link \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "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":
    [
        {
            "keyword": "buyer_email",
            "value": "[email protected]"
        },
            "keyword": "buyer_email",
            "value": "[email protected]",
            "displayOn": "both"
        },
    ]
}'

Response

Payment link created successfully

Name
status
Type
object
is Required
REQUIRED
Description
The status object contains the request status information
Name
id
Type
integer
is optional
Description
Unique and incremental ID of the created payment link, this ID is used to query the payment link information.

EX: 1
Name
url
Type
string
is optional
Description
URL of the payment link. This URL must be sent to the buyer to make the payment.

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

Respuesta

{
    "status": {
        "status": "OK",
        "reason": "PC",
        "message": "La petición se ha procesado correctamente",
        "date": "2021-11-30T15:08:27-05:00"
    },
    "requestId": 1,
    "processUrl": "https://checkout-co.placetopay.com/session/1/cc9b8690b1f7228c78b759ce27d7e80a",
}

POST/api/payment-link/{link_id}

Get a link

This endpoint allows you to query a payment link and get detailed information about it. If the link contains payments, they will also be displayed in the response.

Request

Name
auth
Type
object
is Required
REQUIRED
Description
The auth object is mandatory to securely connect to our services

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":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    }
}'

Response

Payment link queried successfully

Name
id
Type
integer
is Required
REQUIRED
Description
ID of the queried link.

EX: 21
Name
status
Type
string
is Required
REQUIRED
Description
Status of the queried link.

EX: ACTIVE
Allowed values:ACTIVEINACTIVEEXPIRED
Name
url
Type
string
is Required
REQUIRED
Description
URL of the queried link.

EX: http://microsites.test/link/show?genid=26&code=47
Name
expirationDate
Type
string
is optional
Description
Expiration date and time of the queried link in UTC format.

EX: 2024-08-12T08:10:50-05:00
Name
name
Type
string
is Required
REQUIRED
Description
Name associated with the queried link.

EX: Test
Name
reference
Type
string
is Required
REQUIRED
Description
Reference associated with the queried link.

EX: #5321
Name
description
Type
string
is Required
REQUIRED
Description
Description associated with the payment link.

EX: Description of a payment link
Name
totalPayments
Type
integer
is optional
Description
Number of payments allowed through the queried link.

EX: 7
Name
availablePayments
Type
integer
is optional
Description
Number of payments available in the queried link.

EX: 6
Name
paymentExpiration
Type
integer
is optional
Description
Minutes that a payment session lasts before expiring.

EX: 15
Name
amount
Type
integer
is Required
REQUIRED
Description
Amount information to be charged through the payment link
Name
site
Type
object
is Required
REQUIRED
Description
Information about the site associated with the payment link.
Name
metadata
Type
object
is optional
Description
Additional information associated with the payment link.

EX: {"discount":[{"code":17934,"type":"FEDERAL_GOVERNMENT","additional":{"invoice":"123456777"}}]}
Name
payments
Type
array
is optional
Description
List containing all payments made through the link. If no payment has been made, this field will be shown as an empty array.
Name
isGeneric
Type
boolean
is optional
Description
Indicates whether the user can pay multiple times using the same link.

EJ: false

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"
          },
          "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": "+573111111111",
              "document": "1001221123",
              "documentType": "CC"
          }
      }
    ],
    "isGeneric": false
}

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

Disable a link

This endpoint allows you to disable a payment link which will prevent further payments from being made through it.

Request

Name
auth
Type
object
is Required
REQUIRED
Description
The auth object is mandatory to securely connect to our services

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":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    }
}'

Response

Payment link successfully deactivated

Name
status
Type
object
is Required
REQUIRED
Description
The status object contains the request status information
Name
id
Type
string
is Required
REQUIRED
Description
ID of the link that has been deactivated.

Respuesta

{
    "status": {
        "status": "OK",
        "reason": 200,
        "message": "Link de pago desactivado correctamente.",
        "date": "2024-06-07T05:17:14-05:00"
    },
    "id": 14
}