Introduction

This document describes the PSE API. This API offers a REST service for:

• Get available banks
• Generate charge
• Get/Query charge

We also can configure a webhook to notify the API clients when a Charge status has changed. See the Webhook section for details.

Environments

We have two independent environments for development and production applications.

• Staging: https://staging.apiv2.tpaga.co
• Production: https://production.apiv2.tpaga.co

Flow chart

Quick Start Guide

Once you have an active access_token you can start to use our API to process charges.

Here is the detail of each service offered by the API:

1. Authentication

2. Get available banks

3. Generate a charge

4. Get/Query charge

5. Webhook

Authentication

cURL Example:

CLIENT_ID="OXSXZTIC60nB1ghmPevapPWxNT6twIQUeRVLQaCp"
CLIENT_SECRET="XW7qm73qFohu9vT8zObQ0JNb8tS4UfMIg1iepeLw7VmXAHidyEbZbwFEo4ehYeZ3o3GLuKTJhvICZ3RsIgPyDbNlTWnKsz3gkkGrZ66FZOak0nTqfCVvviho7NNLvwyg"
AUTH_STRING=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64 | tr -d '\n')

curl -v --location POST 'https://staging.apiv2.tpaga.co/o/token/' \
  --header "Authorization: Basic $AUTH_STRING" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'

A successful response returns a JSON object in the following format:

{
  "access_token": "<JWT token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope":"read write"
}

An example of a valid request sending the Bearer token:

curl -X GET 'https://staging.apiv2.tpaga.co/api/pse/v1/public/banks' \
  --header 'Authorization: Bearer <JWT token>'

Example to revoke an access token:

curl -X POST 'https://staging.apiv2.tpaga.co/o/revoke_token/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=<JWT token>' \
  --data-urlencode 'client_id=<your-client-id>' \
  --data-urlencode 'client_secret=<your-client-secret>'

This API uses OAuth 2.0 with JWT-based access tokens. Clients must first obtain an access token using the client credentials flow and then include it in subsequent API requests via the Authorization header.

Obtaining an Access Token

Endpoint: /o/token/

HTTP Method: POST

Description: To obtain an access token, send a POST request to the /o/token/ endpoint using HTTP Basic Authentication with your client credentials. Your CLIENT_ID and CLIENT_SECRET must be combined, base64-encoded, and included in the Authorization header.

Request Parameters

Note: Client credentials are provided via the HTTP Basic Authentication header.

Response Parameters

HTTP Responses

Using the Access Token

Include the obtained JWT access token in the Authorization header for subsequent API requests

Token Expiration and Renewal

Access tokens are valid for a limited period (as specified by the expires_in value). We recommend caching your access token and reusing it until it is near expiration. Avoid requesting a new token on every API call. When the token is close to expiring, request a new one to maintain uninterrupted service.

Revoking an Access Token

Endpoint: /o/revoke_token/

HTTP Method: POST

Description: If you need to revoke an access token, send a POST request to the /o/revoke_token/ endpoint.

Request Parameters

Response Parameters

The response body is empty if the token revocation is successful.

HTTP Responses

Environment Considerations

Get available banks

Endpoint: /public/banks

HTTP Method: GET

Description: To generate a charge in the pse API it is necessary to send the code of the bank that will be used, this code is obtained making a GET request to this service.

Example request

curl --location 'https://staging.apiv2.tpaga.co/api/pse/v1/public/banks' \
--header 'Authorization: Bearer <JWT token>'

Example response:

[
    {
        "name": "ALIANZA FIDUCIARIA S A",
        "code": "5016"
    },
    {
        "name": "BAN100",
        "code": "1558"
    },
    {
        "name": "BANCAMIA",
        "code": "1059"
    },
    {
        "name": "BANCO AGRARIO",
        "code": "1040"
    },
    {
        "name": "BANCO AGRARIO DESARROLLO",
        "code": "1081"
    },
    {
        "name": "BANCO AGRARIO QA DEFECTOS",
        "code": "1080"
    },
    {...}
]

Response parameters

HTTP responses

The service will deliver a list of banks which can be used later to generate a charge.

Generate a charge

Endpoint: /public/charge

HTTP Method: POST

Description:

At this point, you will need to show the buyer a form to select the type of person (NATURAL or LEGAL) and the bank you want to use to process your charge.

Once you have the code of the bank that will be used, you must generate the charge by making a POST request to this service.

Example request

curl -X POST \
  https://staging.apiv2.tpaga.co/api/pse/v1/public/charge \
  -H 'Authorization: Bearer <JWT token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "bank_code": "1022",
    "order_id": "abc-123",
    "amount": "10000.0",
    "vat_amount": "10.0",
    "description": "Compra de producto ABC",
    "user_type": "NATURAL",
    "buyer_email": "demo@demo.com",
    "buyer_full_name": "Miguel Rodriguez",
    "document_type": "CE",
    "document_number": "987654321",
    "redirect_url": "http://where-to-go-after-finish-payment-at-pse.com",
    "buyer_phone_number": "3057788996"
  }'

The following is the definition of each of the fields received by this service, each of these values must be sent in the body of the request in json format

Request parameters

Example response:

{
    "token": "pse-c542f18edadb441d8b4639edbfb566e5",
    "order_id": "abc-123",
    "amount": "10000.00",
    "vat_amount": "10.00",
    "description": "Cobro de prueba 2",
    "user_type": "NATURAL",
    "bank_code": "1022",
    "status": "pending",
    "buyer_email": "demo@demo.com",
    "buyer_full_name": "Miguel Rodriguez",
    "document_type": "CE",
    "document_number": "987654321",
    "redirect_url": "http://where-to-go-after-finish-payment-at-pse.com",
    "traceability_code": "3416207",
    "return_code": "SUCCESS",
    "bank_url": "https://registro.desarrollo.pse.com.co/PSENF/index.html?enc=CCnGKyvG0W%2bjZeSCRKHPd1UtFV9Ku20LmblpVQAEyoY%3d",
    "transaction_state": null,
    "rejected_reason": null
}

Response parameters

HTTP responses

Error Details

When the response code is 422, the response body includes details about the invalid data provided. The response will follow this structure:

{
    "error_message": "A descriptive message about the error.",
    "field": "The specific field where the error occurred, or 'non_field_errors' for general validation issues.",
    "value": "The invalid value that caused the error."
}

Example Errors

Get Query charge

Endpoint: /public/charge/token

HTTP Method: GET

Description: This service allows to consult all the information of a charge.

Example request:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/pse/v1/public/charge/pse-c542f18edadb441d8b4639edbfb566e5' \
--header 'Authorization: Bearer <JWT token>'

Request parameters

Response parameters

The response is the same as the one returned at Generate a charge, except the following fields:

HTTP responses

Webhook

This service allows the API client to receive notifications via HTTP requests when a charge has reached a final status.

This is an example of the request that we will send to the configured API client endpoint:

curl -X POST 'https://clienthost.com/some/defined/endpoint' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      {'charge_token': 'pse-c542f18edadb441d8b4639edbfb566e5'}
  }'

How it works

When a charge reaches a final status (authorized, charge-rejected or settled) an HTTP POST request will be sent to a (previously configured) client endpoint. That request will have the following body:

When a webhook notification is sent, the API client should use the received charge_token along with the Get Query charge endpoint to get the complete information related to the charge.

Charge statuses

Operation of charges in PSE

When the buyer completes the charge on the bank's website, they are redirected to the URL that they specified in the field redirect_url when generating the charge.

At this point, you should receive a GET request to the URL you specified, indicating that you are ready to perform a request to the Check a charge service to find out its final status (settled or charge-rejected). Because it's possible that the user abandons the flow without completing the charge, it is important to know that the lifetime of a charge within PSE is about 30 minutes, so that during this maximum period of time a charge can be in a non-final status.

As an API client, you are gonna recieve a webhook notification when a charge has reached a final status. You should be aware that the time it takes for a charge to reach a final state will depend on the actions that make the buyer within the page of the bank.

QA Testing

It is necessary that you previously have credentials assigned, in case you do not have it, please contact with TPAGA operators.

To simulate the charge flow with PSE in the staging environment, the bank "BANCO UNION COLOMBIANO" must be used, whose corresponding bank_code can be obtained using the Get available banks service.

Errors