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

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": "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"
      }
    ]
  }
}

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