Session

The visual experience with which users interact to complete a payment is identified as a session.

POST/api/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 the returnUrl. See more in Skip result
Default 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 as true 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 session
Allowed 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

POST

/api/session

curl -X "POST" https://checkout-test.placetopay.com/api/session \
  -H "Content-Type: application/json" \
  -d '{
      "locale": "es_CO",
      "auth": {
        "login":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "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

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",
}

POST/api/session/:requestId

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

POST

/api/session/:requestId

curl -X "POST" https://checkout-test.placetopay.com/api/session/000000 \
  -H "Content-Type: application/json" \
  -d '{
      "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "nonce": "NjE0OWVkODgwYjNhNw==",
        "seed": "2021-09-21T09:34:48-05:00"
      }
    }'

Response

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": "123 Example Street, Sample City, ST 12345",
        "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": "123 Example Street, Sample City, ST 12345",
        "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": "123 Example Street, Sample City, ST 12345",
          "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"
      }
    ]
  }
}

POST/api/session/:requestId/cancel

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

POST

/api/session/:requestId/cancel

curl -X "POST" https://checkout-test.placetopay.com/api/session/000000/cancel \
  -H "Content-Type: application/json" \
  -d '{
      "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "nonce": "NjE0OWVkODgwYjNhNw==",
        "seed": "2021-09-21T09:34:48-05:00"
      }
    }'

Response

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": "+573111111111"
      },
    "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
  }
}