Session
The visual experience with which users interact to complete a payment is identified as a session.
Create a session
This endpoint allows you to create a new session. In the session the user can complete a payment or subscription.
Request
Structure that contains all the information about the transaction to be processed.
- Name
auth
- Type
- Authentication
- is Required
- REQUIRED
- Description
Site authentication. See more in Authentication
- Name
payment
- Type
- PaymentRequest
- is Required
- REQUIRED
- Description
Requested payment information.
- Name
expiration
- Type
- string
- is optional
- Description
Expiration date of a session. The user must finish the process before this date. The expiration time must be at least 5 minutes from the time of creation. See more in Expiration date
e.g.:2024-09-03T12:23:39-05:00
Format:date-time
- Name
ipAddress
- Type
- string
- is Required
- REQUIRED
- Description
IP address of the user who will perform the process.
e.g.:134.10.163.36
Example:134.10.163.36
- Name
userAgent
- Type
- string
- is Required
- REQUIRED
- Description
User Agent of the user's browser that will carry out the process.
e.g.:
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
Example:PlacetoPay Sandbox
- Name
returnUrl
- Type
- string
- is Required
- REQUIRED
- Description
Return URL, to this url the user is redirected once the session ends. Occurs when the user clicks on Return to commerce.
e.g.:
https://merchant.com/return
Example:https://commerce.test/return
- Name
locale
- Type
- string
- is optional
- Description
Language in which the request and the session will be processed. See more in Location
e.g.:
en_US
,es_CO
Example:en_US
Format:regex
Pattern:^\w{2}\_[A-Z]{2}
- Name
buyer
- Type
- Person
- is optional
- Description
User data buyer, refers to the user who is buying a product or service.
When a session is created: It can be sent if you know the user who is making the purchase, as it helps to complete the session information. If this data is sent, the user will have their personal data pre-filled and will be able to change them at Checkout.
- Name
payer
- Type
- Person
- is optional
- Description
Data of the user payer, refers to the owner of the means of payment or user who paid the requested amount.
When a session is created: It should only be used when you want to "force" the data of the user who will complete the process. If this data is sent, the user will have their personal data pre-filled but will not be able to change them.
- Name
subscription
- Type
- SubscriptionRequest
- is optional
- Description
When sent, a subscription session is generated.
The user registers a means of payment so that later charges are made on that means of payment.
- Name
fields
- Type
- array[NameValuePair]
- is optional
- Description
Structure to relate additional information in the process. See more in Additional Fields
- Name
paymentMethod
- Type
- string
- is optional
- Description
It is used to restrict the payment methods available at checkout. Multiple codes can be sent separated by commas. See more in Payment methods
e.g.:
visa,master,pse
Example:visa
- Name
cancelUrl
- Type
- string
- is optional
- Description
Cancellation URL, the user is redirected to this url when he decides not to continue with the process. Occurs when the user clicks on I don't want to continue
e.g.:
https://merchant.com/cancel
Example:https://commerce.test/cancel
- Name
skipResult
- Type
- boolean
- is optional
- Description
If
true
is sent, when the user finishes the process the session result page will not be displayed, instead they will be redirected to thereturnUrl
. See more in Skip resultDefault value:false
- Name
noBuyerFill
- Type
- boolean
- is optional
- Description
By default, the data sent as
buyer
is pre-filled in the Checkout interface to speed up the payment process, if this parameter is sent astrue
then this pre-fill will not be done.Default value:false
- Name
type
- Type
- string
- is optional
- Description
Parameter used for pre-authorization type sessions
Only
checkin
is supported to generate a pre-authorization sessionAllowed values:checkin
Example:checkin
- Name
metadata
- Type
- metadata
- is optional
- Description
Key-value structure used to send additional information and determine specific behaviors during session processing.
Request
curl -X "POST" https://checkout-test.placetopay.com/api/session \
-H "Content-Type: application/json" \
-d '{
"locale": "es_CO",
"auth": {
"login":"c51ce410c124a10e0db5e4b97fc2af39",
"tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
"nonce":"NjE0OWVkODgwYjNhNw==",
"seed":"2021-09-21T09:34:48-05:00"
},
"payment": {
"reference": "1122334455",
"description": "Prueba",
"amount": {
"currency": "USD",
"total": 100
}
},
"expiration": "2021-12-30T00:00:00-05:00",
"returnUrl": "https://dnetix.co/p2p/client",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox"
}'
Response
OK
- Name
status
- Type
- Status
- is optional
- Description
Structure that contains the response information about a request or payment, and reports the current status of the same.
- Name
requestId
- Type
- integer
- is optional
- Description
- Name
processUrl
- Type
- string
- is optional
- Description
Response
{
"status": {
"status": "OK",
"reason": "PC",
"message": "The request has been processed successfully",
"date": "2021-11-30T15:08:27-05:00"
},
"requestId": 1,
"processUrl": "https://checkout-co.placetopay.com/session/1/cc9b8690b1f7228c78b759ce27d7e80a",
}
Query a session
This endpoint allows you to obtain the information of the session, if there are transactions in the session, the details of the same are shown.
Params
- Name
requestId
- Type
- requestId
- is Required
- REQUIRED
- Description
Request
- Name
auth
- Type
- Authentication
- is Required
- REQUIRED
- Description
Site authentication. See more in Authentication
Request
curl -X "POST" https://checkout-test.placetopay.com/api/session/000000 \
-H "Content-Type: application/json" \
-d '{
"auth": {
"login": "c51ce410c124a10e0db5e4b97fc2af39",
"tranKey": "VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
"nonce": "NjE0OWVkODgwYjNhNw==",
"seed": "2021-09-21T09:34:48-05:00"
}
}'
Response
OK
- Name
requestId
- Type
- string|number|integer
- is optional
- Description
Request id
Example:1
- Name
status
- Type
- Status
- is optional
- Description
Structure that contains the response information about a request or payment, and reports the current status of the same.
- Name
request
- Type
- RedirectRequest
- is optional
- Description
Structure that contains all the information about the transaction to be processed.
- Name
payment
- Type
- Transaction
- is optional
- Description
- Name
subscription
- Type
- SubscriptionResponse
- is optional
- Description
Structure containing information for the subscription payment method.
Response
{
"requestId": 1,
"status": {
"status": "APPROVED",
"reason": "00",
"message": "The request has been successfully approved",
"date": "2022-07-27T14:51:27-05:00"
},
"request": {
"locale": "es_CO",
"payer": {
"document": "1122334455",
"documentType": "CC",
"name": "John",
"surname": "Doe",
"company": "Evertec",
"email": "[email protected]",
"mobile": "+5731111111111",
"address": {
"street": "Calle falsa 123",
"city": "Medellín",
"state": "Poblado",
"postalCode": "55555",
"country": "CO",
"phone": "+573111111111"
}
},
"buyer": {
"document": "1122334455",
"documentType": "CC",
"name": "John",
"surname": "Doe",
"company": "Evertec",
"email": "[email protected]",
"mobile": "+5731111111111",
"address": {
"street": "Calle falsa 123",
"city": "Medellín",
"state": "Poblado",
"postalCode": "55555",
"country": "CO",
"phone": "+573111111111"
}
},
"payment": {
"reference": "12345",
"description": "Prueba de pago",
"amount": {
"currency": "COP",
"total": 2000,
"taxes": [
{
"kind": "valueAddedTax",
"amount": 1000,
"base": 0
}
],
"details": [
{
"kind": "discount",
"amount": 1000
}
]
},
"allowPartial": false,
"shipping": {
"document": "1122334455",
"documentType": "CC",
"name": "John",
"surname": "Doe",
"company": "Evertec",
"email": "[email protected]",
"mobile": "+5731111111111",
"address": {
"street": "Calle falsa 123",
"city": "Medellín",
"state": "Poblado",
"postalCode": "55555",
"country": "CO",
"phone": "+573111111111"
}
},
"items": [
{
"sku": "12345",
"name": "product_1",
"category": "physical",
"qty": "1",
"price": 1000,
"tax": 0
}
],
"fields": [
{
"keyword": "_test_field_value_",
"value": "_test_field_",
"displayOn": "approved"
}
],
"recurring": {
"periodicity": "D",
"interval": "1",
"nextPayment": "2019-08-24",
"maxPeriods": 1,
"dueDate ": "2019-09-24",
"notificationUrl ": "https://checkout.placetopay.com"
},
"subscribe": false,
"dispersion": [
{
"agreement": "1299",
"agreementType": "MERCHANT",
"amount": {
"currency": "USD",
"total": 200
}
}
],
"modifiers": [
{
"type": "FEDERAL_GOVERNMENT",
"code": 17934,
"additional": {
"invoice": "123345"
}
}
]
},
"subscription": {
"reference": "12345",
"description": "Example description",
"fields": {
"keyword": "1111",
"value": "lastDigits",
"displayOn": "none"
}
},
"fields": [
{
"keyword": "_processUrl_",
"value": "https://checkout.redirection.test/session/1/a592098e22acc709ec7eb30fc0973060",
"displayOn": "none"
}
],
"paymentMethod": "visa",
"expiration": "2019-08-24T14:15:22Z",
"returnUrl": "https://commerce.test/return",
"cancelUrl": "https://commerce.test/cancel",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox",
"skipResult": false,
"noBuyerFill": false,
"type": "checkin"
},
"payment": [
{
"status": {
"status": "APPROVED",
"reason": "00",
"message": "The request has been successfully approved",
"date": "2022-07-27T14:51:27-05:00"
},
"internalReference": 12345,
"reference": "12345",
"paymentMethod": "visa",
"paymentMethodName": "Visa",
"issuerName": "JPMORGAN CHASE BANK, N.A.",
"amount": {
"from": {
"currency ": "COP",
"total ": 10000
},
"to": {
"currency ": "COP",
"total ": 10000
},
"factor": 1
},
"receipt": "052617800175",
"franchise": "PS_VS",
"refunded": false,
"authorization": "965960",
"processorFields": [
{
"keyword": "1111",
"value": "lastDigits",
"displayOn": "none"
}
],
"dispersion": null,
"agreement": null,
"agreementType": null,
"discount": {
"base": 3000,
"code": "17934",
"type": "FRANCHISE",
"amount": 1000
},
"subscription": null
}
],
"subscription": {
"status": {
"status": "OK",
"reason": "00",
"message": "The request has been successfully approved",
"date": "2022-07-27T14:51:27-05:00"
},
"type": "token",
"instrument": [
{
"keyword": "token",
"value": "a3bfc8e2afb9ac5583922eccd6d2061c1b0592b099f04e352a894f37ae51cf1a",
"displayOn": "none"
},
{
"keyword": "subtoken",
"value": "8740257204881111",
"displayOn": "none"
},
{
"keyword": "franchise",
"value": "visa",
"displayOn": "none"
},
{
"keyword": "franchiseName",
"value": "Visa",
"displayOn": "none"
},
{
"keyword": "issuerName",
"value": "JPMORGAN CHASE BANK, N.A.",
"displayOn": "none"
},
{
"keyword": "lastDigits",
"value": "1111",
"displayOn": "none"
},
{
"keyword": "validUntil",
"value": "2029-12-31",
"displayOn": "none"
},
{
"keyword": "installments",
"value": null,
"displayOn": "none"
}
]
}
}
Cancel a session
This endpoint allows you to cancel a session without any approved payment or a cash transaction that has not been paid.
Params
- Name
requestId
- Type
- requestId
- is Required
- REQUIRED
- Description
Identifier of the session to be cancelled
Request
Request structure to cancel a session.
- Name
auth
- Type
- Authentication
- is Required
- REQUIRED
- Description
Site authentication. See more in Authentication
Solicitud
curl -X "POST" https://checkout-test.placetopay.com/api/session/000000/cancel \
-H "Content-Type: application/json" \
-d '{
"auth": {
"login": "c51ce410c124a10e0db5e4b97fc2af39",
"tranKey": "VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
"nonce": "NjE0OWVkODgwYjNhNw==",
"seed": "2021-09-21T09:34:48-05:00"
}
}'
Response
OK
- Name
status
- Type
- Status
- is optional
- Description
Structure that contains the response information about a request or payment, and reports the current status of the same.
- Name
session
- Type
- RedirectInformation
- is optional
- Description
Response structure to a request for transaction information.
Respuesta
{
"status": {
"status": "OK",
"reason": "00",
"message": "The request has been processed successfully.",
"date": "2025-07-11T14:05:44-05:00"
},
"session": {
"requestId": 28,
"status": {
"status": "REJECTED",
"reason": "MC",
"message": "The request has been cancelled by the merchant",
"date": "2025-07-11T14:05:44-05:00"
},
"request": {
"locale": "es_CO",
"payer": {
"document": "118877455",
"documentType": "CC",
"name": "John",
"surname": "Doe",
"email": "[email protected]",
"mobile": "+573123123123"
},
"payment": {
"reference": "Ord: 1001/2023",
"description": "_pueba pagoEfectivo",
"amount": {
"currency": "USD",
"total": 20000
},
"allowPartial": false,
"subscribe": false,
"fields": [
{
"keyword": "_test_field_",
"value": "_test_field_value_",
"displayOn": "payment"
}
]
},
"returnUrl": "https://mysite.com/response/32120",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox",
"expiration": "2025-07-11T19:25:39.497Z"
},
"payment": null,
"subscription": null
}
}