How Checkout works

Checkout allows you to receive payments online making a very simple integration from your site or application.

Lifecycle

  1. When your users are ready to complete the checkout process, your app should create a CheckoutSession.
  2. Redirect the user to the URL provided, this URL contains our Checkout with all its functionalities ready.
  3. The user enters the required data to complete the payment.
  4. The user is redirected back to the merchant site.
  5. After the transaction, a notification is sent so that the application knows the status of the payment.

To use PlacetoPay Checkout, you need to do a code integration using HTTP services, where your app or online store will redirect users to Checkout to complete the payment process. Here are the steps needed to start the integration.

Integration

The following diagram describes visually and in more detail the life cycle of a payment session in Checkout.

React Flow

Security Considerations

Webcheckout endpoints MUST NOT be accessed directly from the browser (e.g., JavaScript/AJAX). Doing so exposes API credentials and sensitive data to risks such as:

  • Key interception by malicious scripts
  • Data exposure in the client console
  • Vulnerability to XSS attacks

Start Checkout

Create a payment session
To accept a payment through Checkout, it is necessary to create a payment session (Checkout Session) using the method API - Create session (CreateRequest).
Calling this service will return the process URL (processUrl) and the request identifier (requestId). You can see more in the section Create Session

Registration of Payment in Process
In your system, create a record that relates the payment in progress to the requestID provided.
The initial status of all payments is pending (PENDING).

User Redirection
The user should be redirected to the process URL (processUrl) provided by PlacetoPay Checkout.

Payment or Subscription Process
In the Checkout interface, the user will complete the payment or subscription process. Checkout will take care of collecting all the necessary data.

Redirection back to the merchant site
Once the checkout process is complete, the user can be redirected back to the return URL (returnUrl) specified in the initial request (CreateRequest).

At this point it is likely that the payment process has finished. To know the status of the payment you must wait for the notification or check the status of the session.

Asynchronous notification

When a session has a final status, PlacetoPay will send an asynchronous notification to your site informing you of the completion of the payment process. Be sure to properly handle this notification to maintain data integrity.

Session query

Sessions must be queried in order to complete the lifecycle.

Query session status
When you arrive at the merchant's site, you must check the status of the session. This can be achieved using the API - Query session (getRequestInformation) method.

Update and Business Rules
According to the final status of the payment obtained, you must execute the corresponding business rules and update the information related to the payment in your system..

Sessions States

Sessions can go through different states, each with its own meaning and sequence of changes. Below we present the possible states and how they relate to each other:

PENDING Pending: It occurs in three situations: firstly, it's the initial state of the session, indicating that the process is waiting for user actions; secondly, when there are rejected transactions, allowing the user the opportunity to make new attempts; and lastly, when there is a transaction pending validation, indicating that the session is in a waiting state until the transaction is confirmed and validated. In summary, it is a waiting state and indicates that the process is not yet completed.

APPROVED Approved: This state occurs when transactions have been approved, and the process has been successfully completed. This is a final process state.

REJECTED Rejected: This state occurs when the session is canceled by the user. It can also occur when the session reaches expiration time without an approved payment. This is a final state of the process.

APPROVED_PARTIAL Partial Approved: It occurs in partial payment sessions when the user has paid a part of the total requested amount but another part is still pending or has failed. At this time the user can still complete the entire payment with other transactions.

PARTIAL_EXPIRED Partial Expired: It occurs in partial payment sessions when the user has only paid a portion of the total amount requested and the time available to complete the payment has already ended. At this time the process has already ended and cannot be completed. This is a final state of the process.

States in sessions

React Flow

States in partial payment sessions

React Flow

Whats Next?

Done, now that you understand the life cycle you can continue with: