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

Payment Preauthorization

A pre-authorization session is a session in which the user completes the process and the requested amount is reserved on their credit card, after the reservation the amount can be modified, confirmed or canceled.

This workflow is used in order to reserve (CHECKIN) an amount of money in the cardholder to later debit it, in this case (CHECKOUT). This amount may change over time (REAUTHORIZATION) according to the needs of the business or changes in the services chosen by the cardholder. Finally, the reverse (REVERSE) is a type of transaction, which allows you to reverse an approved or debited payment with the internal reference code.

• The "action" porperty must be checkin.
• The payment reference will be reused in subsequent REAUTHORIZATION and CHECKOUT operations.
• The payment currency will also remain the same in REAUTHORIZATION and CHECKOUT.
• Pre-authorization payments are not allowed when you want to make a mixed payment.
• Pre-authorization payments with scatter values are not allowed.

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

Reauthorization

Not applicable to Puerto Rico

It is applied on pre-authorization transactions and is used to modify the previously reserved amount.

The REAUTHORIZATION type transaction is used to modify the amount defined as previously separated guarantee deposit, with a CHECKIN type transaction. This performs a new authorization by the bank.

• The payment reference is overwritten by the original CHECKIN session.
• The payment currency is overwritten by the original CHECKIN session.
• The values for internalReference and authorization must match those provided in the CHECKIN response within the preAuthorization node.
• Multiple REAUTHORIZATION transactions can be performed before CHECKOUT.
• Each reauthorization must be for an amount greater than 0.

After this operation, the pre-authorization remains in a pending state until a CHECKOUT is performed.

{
    ...
    "internalReference": 1, //internal reference code
    "amount": {
        "currency": "USD",
        "total": 100
    },
    "action": "reauthorization"
    ...
}

Checkout

It is applied to pre-authorization transactions and is used to confirm and close the transaction with the indicated amount.

The CHECKOUT type transaction is used to confirm the security deposit amount previously separated, with a CHECKIN/REAUTHORIZATION type transaction. This formalizes the purchase transaction with the bank.

• A CHECKOUT can be performed without a prior REAUTHORIZATION.
• The payment reference is overwritten by the original CHECKIN session.
• The payment currency is overwritten by the original CHECKIN session.
• The values for internalReference and authorization must match those provided in the CHECKIN response within the preAuthorization node.
• If the CHECKOUT amount is 0, the pre-authorization is canceled, and the retained amount is released.

{
    ...
    "internalReference": 1, //internal reference code
    "amount": {
        "currency": "USD",
        "total": 100
    },
    "action": "checkout"
    ...
}

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 RedirectRequest.

{
    ...
    "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

A payment can be converted into payment and subscription at the same time, to carry out this flow it is important to add the attribute subscribe to true in the payment object as follows

To use this session type, you must set the payment.subscribe property to true

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

In the payment process, the user can choose if he wants to subscribe to the means of payment.