Create a Session

Session is the term we use to refer to the payment process with which your users interact in Checkout.

To create a session you must consume our API according to your needs, learn the details of the API in API - Create Session.

Authentication To create a session you must authenticate with our API, learn the details in Authentication

Localization You can choose the language of the session using the parameters of the api, learn the details in Localization

Basic Payment

A basic payment session is a session in which you expect to receive a single payment from a user.

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Payment by Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
    }
    ...
}

Partial payment

A partial payment session is a session in which a user can make several transactions of different amounts or with different payment methods until the total requested in the same session is completed.

To use this functionality, the payment.allowPartial property must be sent as true.

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Payment by Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
        "allowPartial": true
    }
    ...
}

When a partial payment session is made, new scenarios appear that must be controlled:

• The session ends with the APPROVED PARTIAL status, it occurs when at least one APPROVED transaction was made in the session, but the total requested amount was not completed.
• The session ends with the PARTIAL_EXPIRED status, it occurs when at least one APPROVED transaction was made in the session, but the total amount requested was not completed and the session expired.

Partial sessions also have additional conditions such as:

• Taxes are not accepted, since taxes cannot be divided into different transactions.

Recurring payment

A recurring payment session is a session in which the user completes the process with a credit card, and from that moment on, automatic charges are periodically made to the payment method. For example, in the payment of a monthly payment or subscription to a service.

To use this functionality, the payment.recurring property must be sent with the Recurrence structure..

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Payment by Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
        "recurring": {
            "periodicity": "D",
            "interval": "1",
            "nextPayment": "2024-08-24",
            "maxPeriods": 1,
            "dueDate ": "2024-09-24",
            "notificationUrl ": "https://merchanturl.com/notify"
        },
    }
    ...
}

• The nextPayment attribute is not mandatory, in case it is not sent, it is calculated depending on the interval and periodicity attribute, in case it is declared it must be a future date to the current date.
• In the case of failing a recurring charge, it will continue to be retried once a day for 3 days, if after this an approved transaction is not obtained, the recurrence is canceled to the cardholder.
• The recurrence is stopped trying if the first response does not make sense to retry (Card invalid, stolen, etc.), that is, it is retried only if it is due to balance.
• Recurrences can only be canceled in the PlacetoPay administrative console.

Dispersion payment

A dispersal session is a session in which the total amount of the payment will be divided into different destinations.

To use this session type, you must pass the payment.dispersion property which contains an array of DispersionRequests

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Payment by Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
        "dispersion": [
            {
                "amount": {
                    "total": 700,
                    "currency": "USD"
                },
                "agreement": 30,
                "agreementType": "AIRLINE"
            },
            {
                "amount": {
                    "total": 300,
                    "currency": "USD"
                },
                "agreementType": "MERCHANT"
            }
        ],
    }
    ...
}

The payment can be divided into different registered agreements, it also allows each part of the transaction to be processed by different providers.

To make use of this functionality it is important to know the identifier of the agreement (agreement) to which the payment is directed. If no agreement value is added, the payment method configured on the site of the session will be taken by default, it is also necessary to indicate the type of agreement (aggrementType), in this case MERCHANT or AIRLINE.

• Partial payments are not allowed when creating a dispersal session.
• No pre-authorization payments are allowed when creating a dispersal session.
• The total sum of the scatters must be equal to the total payout.
• All scatter coins must be equal to the payout currency

For the sending of taxes, it is important that it is in the amount structure of each of the dispersions

{
    ...
    "payment": {
        ...
        "dispersion": [
            {
                "amount": {
                    "total": 700,
                    "currency": "USD",
                    "taxes": [
                        {
                            "kind": "airportTax",
                            "amount": 16.13
                        }
                    ],
                    "details": [
                        {
                            "kind": "tip",
                            "amount": 11
                        }
                    ]
                },
                "agreement": 30,
                "agreementType": "AIRLINE",
            },
        ],
    }
    ...
}

Preauthorization payment

Preauthorization allows you to reserve an amount on a customer’s card via a Web Checkout session. This is useful when the final charge amount is not known upfront—common in scenarios like hospitality, mobility, or equipment rentals.

The preauthorization flow includes three key steps:

• Check-in: Reserve a specific amount on the customer's card without immediate capture.
• Reauthorization: Adjust the reserved amount if the expected charge changes.
• Checkout: Capture the final amount or release the reservation.

For more information about the Preauthorization payment flow, see Payments/Preauthorization

Below, we will explore each step in detail to help you integrate preauthorization payments effectively.

Step 1: Create a session for the preauthorization flow (Check-in)

Initiate the preauthorization by creating a session with type checkin. This reserves the funds on the customer’s card without charging them.

Send a RedirectRequest to API Web Checkout -> Session create:

• type must be checkin
• Mixed or dispersion payments are not allowed
• The currency remains fixed throughout the entire flow

{
    ...
    "type": "checkin",
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Payment Preauthorization",
        "amount": {
            "currency": "USD",
            "total": 1000
        }
    }
    ...
}

Once the session is created, redirect the user to RedirectResponse.processUrl. Once completed, API Web Checkout -> Query the session (getRequestInformation) in order confirm the status:

{
    "auth": ...
}

The RedirectInformation.payment is an array of attemps about payment, if the RedirectInformation.status is APPROVED, identify the successful attempt.

Store RedirectInformation.payment.[n].internalReference to use in subsequent REAUTHORIZATION and CHECKOUT operations.

Step 2: Adjust the reserved amount (reauthorization)

This optional step allows you to update the held amount before capturing it.

This is done by sending a TransactionActionRequest to API Web Checkout -> Transaction Actions:

• action must be reauthorization
• You can perform multiple reauthorizations
• You must include the internalReference from the previous step.
• The currency must match the Check-in

{
    "auth": ...,
    "action": "reauthorization"
    "internalReference": 35,
    "amount": {
        "currency": "USD",
        "total": 1500
    },
    ...
}

Step 3: Finalize the transaction (Checkout)

This step captures or releases the held amount.

This is done by sending a TransactionActionRequest to API Web Checkout -> Transaction actions:

• action must be checkout
• If payment.amount.total is 0, the held amount is released.
• You must include the internalReference from the previous step.
• The currency must match the Check-in

{
    "auth": ...,
    "action": "checkout",
    "internalReference": 35,
    "amount": {
        "currency": "USD",
        "total": 2000
    },
    ...
}

This flow applies exclusively to Web Checkout, where the initial step involves a browser session, and follow-up actions are performed via API. Ensure your system securely stores the internalReference value to properly complete the flow.

Subscription

A subscription session is a session in which the user enters a means of payment to tokenize it and that can then be used to collect on that means of payment.

The subscription allows you to securely store (tokenizing) a user's means of payment, so that you can later make payments related to it.

To make use of this functionality it is necessary to send the subscription structure in the CreateSessionRequest.

{
    ...
    "subscription": {
        "reference": "3110",
        "description": "A trial subscription"
    },
    ...
}

Charge on a tokenized means of payment

When a subscription is made, a token is obtained, with this token you can charge the client.

The response structure contains all the information from the original request and a subscription structure (subscription) with an instrument (instrument) represented as a token.

{
    ...
    "payment": {
        "reference": "1122334455",
        "description": "Test",
        "amount": {
            "currency": "USD",
            "total": 100
        }
    },
    "instrument": {
        "token": {
            "token": "e07ca9986cf0ecac8a557fa11c07bf37ea35e9e3e3a4180c49"
        }
    },
    ...
}

The token information must be stored on your site and related to the user and/or product. After having the token, you can generate charges to the tokenized payment method using the collect service.

Payment with subscription

You can allow users to save their payment method during a regular transaction by enabling the subscription flow. This flow securely stores the payment method for future use, always requiring the user's explicit consent.

This flow is useful for:

• Preparing future charges (e.g., for subscriptions or recurring payments).
• Reducing friction during checkout by reusing stored payment details.
• Charging the user when they are not present, such as in automatic renewals.

1. Create a payment session with subscription option

To enable the option to save the payment method during the checkout process, include the property
subscribe: true within the payment structure in the CreateSessionRequest.

{
  ...
  "payment": {
    "reference": "PAY_ABC_1287",
    "description": "Pago por Placetopay",
    "amount": {
      "currency": "USD",
      "total": 1000
    },
    "subscribe": true
  }
  ...
}

This enables the option for the user to authorize the storage of the payment method (tokenization) when completing the payment.

2. Payment method saved by the user

During the checkout flow, the user will be shown an option to authorize the storage of their payment method.
This authorization is required for the method to be tokenized and made available for future payments.

3. Retrieve the saved payment method token

If the user authorized the saving of their payment method during the checkout process, you can retrieve the generated token (the identifier of the tokenized payment method) once the session is completed.

To do so, send a request to the Query a session endpoint using the corresponding requestId. The token will be available in the subscription.instrument field of the response, if the process was successful.

{
  "requestId": 1,
  "status": {...},
  "request": {
    ...
    "payment": {
      "reference": "12345",
      "description": "Prueba de pago",
      "amount": {
        "currency": "COP",
        "total": 2000,
      },
      "subscribe": true,
    },
  },
  "payment": [
    {
      "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "La petición ha sido aprobada exitosamente",
        "date": "2022-07-27T14:51:27-05:00"
      },
      ...
    }
  ],
  "subscription": {
    "status": {
      "status": "OK",
      "reason": "00",
      "message": "La petición ha sido aprobada exitosamente",
      "date": "2022-07-27T14:51:27-05:00"
    },
    "type": "token",
    "instrument": [
        {
            "keyword": "token",
            "value": "a3bfc8e2afb9ac5583922eccd6d2061c1b0592b099f04e352a894f37ae51cf1a",
            "displayOn": "none"
        },
        {
            "keyword": "subtoken",
            "value": "8740257204881111",
            "displayOn": "none"
        },
        ...
    ]
  }
}

4. Use the token for future charges

Once the payment method token is obtained, you can reuse it to perform future charges without requiring additional interaction from the user.

For more details on this process, see the section:
➡️ Charge a tokenized payment method