Documentación

Integrar PSE

En este guía, te proveeremos toda la información que necesitas para integrar y usar PSE de forma eficiente. Pagos Seguros en Línea (PSE) es un sistema de pago electrónico en Colombia que permite a los comercios ofrecer a sus clientes la capacidad realizar compras y pagos a través de internet debitando los recursos de su cuenta de ahorros, corriente o depósito electrónico.

Suggest Edits
PSE payment method

PSE payment method

Overview

Payment Flow

  1. Payment selection: The user selects PSE as their payments method on your website or app.
  2. PSE form completion: The user completes the PSE form with the details required to start a PSE transaction, such as: bank, user's account name, person type, identification and phone number.
  3. Redirection to selected bank: After completing the form, the user is redirected to the selected bank to complete the transaction.
  4. Redirection to merchant page: Once the transaction has been completed, the user will be redirected to a page defined by the merchant, showing the details of the transaction.

Supported Operations

  • Purchase
  • Webhooks

Integration Steps

Environments

Postman collection

PSE - Colombia

Types of integration

The PSE processor is available through two types of integrations:

  • Direct API integration. To integrate PSE through Deuna's API, please to the steps listed in the guide below.
  • Widget integration. To integrate PSE through the Payment Widget, please refer to this integration guide.

Direct API integration

1 - Creating a User

Create an user with DEUNA in order to get the authorization token to perform the purchase later. This API will return back a User's token which will be required to follow the next steps.

👍

We recommend to use the OTP to get a new token each time your customer confirms through the SMS or Email the code. Also, you can use an External Authentication login to manage the user auth tokens by your own without request them the OTP. Talked to your Sales Engineer for further guidance.

To create a user, follow the API Reference, the document could be any of the available Colombian documents such as: CC, CE, TI, PP, NIT, RC and DE. In case the email used already exists, the API will return the message user already exists, so you can proceed to Request the OTP and then, Login with the OTP to obtain a fresh user tokenand proceed with the purchase.

🚧

Creating a User is optional, in case your integration uses the Purchase V2 endpoint.

2 - Making a PSE Purchase

To create a PSE transaction with Deuna, the merchant must:

  1. Create an Order, which will have information such as amounts (e.g., taxes, shipping, items, discounts), any prior shipping/billing information collected from the user, browser from the user, etc.
  2. Perform a Purchase transaction, which will have the information collected from the PSE form filled by the user such as full name, document number, document type, phone number, person type (natural or legal), bank and callback URL to redirect the user to a merchant page.

In order to perform this transaction as a one-step process, this guide will use the Purchase V2 endpoint; otherwise, you can refer to the Create Order and Purchase V1 endpoint to perform the steps above, respectively.

According to the Purchase V2 endpoint, here's a table showing the required fields to perform a PSE transaction:

FieldDescriptionExample
payer_infor.person_typeRefers to the type of person, either natural or legalLEGAL_PERSON
pse.financial_institutionRefers to the code of the selected bank1022
pse.financial_institution_nameRefers to the name of the bankBANCO UNION COLOMBIANO
callback_urls.on_successRefers to the redirection URL after completing the PSE transactionhttps://example.com/
browser_details.ip_addressRefers to the IP address from the browser used by the user155.95.122.206
billing_address.identification_typeRefers to the type of the identity document. In the case of PSE, the available documents are: CC,CE, TI, PP, NIT, RCandDECC
billing_address.identificationRefers to the identification number of the user1234567890
billing_address.first_nameRefers to the first name of the userJuan
billing_address.last_nameRefers to the last name of the userPérez
billing_address.phoneRefers to the phone number in format E.164+14155552671
billing_address.cityRefers to the city for billing the userBogotá
billing_address.street1Refers to primary address information for billing the userAvenida Carrera 72 80
billing_address.street2Refers to apartment and suite information for billing the user94

{
	"order_type": "DEUNA_CHECKOUT",
	"payer_info": {
		"email": "[email protected]",
		"person_type": "NATURAL_PERSON" // Obtained from PSE form filled by the user
	},
	"callback_urls": {
		"on_success": "https://example.com/" // Redirection after completing PSE transaction
	},
	"payment_source": {
		"method_type": "bank_transfer",
		"processor": "payu_pse",
		"method_type_specific_fields": {
			"pse": {
				"financial_institution": "1022", // Code of selected bank, obtained from PSE form
				"financial_institution_name": "BANCO UNION COLOMBIANO" // Name of bank, obtained from PSE form
			}
		}
	},
	"order": {
		"order_id": "d81fe7bf-748b-4a7a-bc8f-7be98c8ae748",
		"store_code": "all",
		"currency": "COP",
		"total_tax_amount": 200000,
		"items_total_amount": 1900000,
		"sub_total": 1900000,
		"total_amount": 2100000,
		"items": [
			{
				"id": "79",
				"name": "10 ALITAS VOLANTE",
				"description": "10 alitas picantes",
				"options": "string option",
				"total_amount": {
					"amount": 1900000,
					"currency": "COP",
					"currency_symbol": "$"
				},
				"unit_price": {
					"amount": 850000,
					"currency": "COP",
					"currency_symbol": "$"
				},
				"tax_amount": {
					"amount": 100000,
					"currency": "COP",
					"currency_symbol": "$"
				},
				"quantity": 2,
				"uom": "string",
				"upc": "string",
				"sku": "SKU-11021",
				"isbn": "12-345-678-90123",
				"brand": "Bolt Swagstore",
				"manufacturer": "Bolt Factory",
				"category": "hats",
				"color": "Red",
				"size": "XXL",
				"weight": {
					"weight": 22,
					"unit": "kg"
				},
				"image_url": "https://boltswagstore.com/inventory/hats/red-hat.png",
				"details_url": "https://boltswagstore.com/inventory/hats/red-hat.png",
				"type": "physical",
				"taxable": true
			}
		],
		"billing_address": {
			"first_name": "Juan",
			"last_name": "Rodríguez",
			"email": "[email protected]",
			"identification": "1234567890", // Document number obtained from PSE form
			"identification_type": "CC", // Document type obtained from PSE form
			"phone": "+578315263363",
			"address1": "Avenida Carrera 72 80",
			"address2": "94",
			"zipcode": "110110",
			"city": "Bogota",
			"state_name": "Bogota",
			"country": "CO"
		},
		"shipping_address": {
			"first_name": "Juan",
			"last_name": "Rodríguez",
			"email": "[email protected]",
			"identification": "14201225",
			"identification_type": "CC",
			"phone": "+578315263363",
			"address1": "Avenida Carrera 72 80",
			"address2": "94",
			"zipcode": "110110",
			"city": "Bogota",
			"state_name": "Bogota",
			"country": "CO"
		},
		"browser_details": {
			"ip_address": "155.95.122.206"
		}
	}
}

After performing the Purchase, Deuna's API will respond with a redirection URL in the authorization_bank_transfer node, which the Merchant must redirect the user to complete the bank transfer through PSE. Here's an example on the expected response:

{
	"order_type": "DEUNA_CHECKOUT",
	"order_token": "db3fc147-2a4e-460f-a874-f6f79b1e651c",
	"order": {
		"order_id": "d81fe7bf-748b-4a7a-bc8f-7be98c8ae748",
		"store_code": "all",
		"currency": "COP",
		"tax_amount": 0,
		"display_tax_amount": "",
		"shipping_amount": 0,
		"display_shipping_amount": "COP 0,00",
		"items_total_amount": 1900000,
		"display_items_total_amount": "COP 19.000,00",
		"sub_total": 1900000,
		"display_sub_total": "COP 19.000,00",
		"total_amount": 2100000,
		"display_total_amount": "COP 21.000,00",
		"items": [
			{
				"id": "79",
				"name": "10 ALITAS VOLANTE",
				"description": "10 alitas picantes",
				"options": "string option",
				"total_amount": {
					"amount": 1900000,
					"original_amount": 0,
					"display_amount": "COP 19.000,00",
					"display_original_amount": "COP 0,00",
					"currency": "COP",
					"currency_symbol": "$",
					"total_discount": 0,
					"display_total_discount": "COP 0,00"
				},
				"unit_price": {
					"amount": 850000,
					"display_amount": "COP 8.500,00",
					"currency": "COP",
					"currency_symbol": "$"
				},
				"tax_amount": {
					"amount": 100000,
					"display_amount": "COP 1.000,00",
					"currency": "COP",
					"currency_symbol": "$"
				},
				"quantity": 2,
				"uom": "string",
				"upc": "string",
				"sku": "SKU-11021",
				"isbn": "12-345-678-90123",
				"brand": "Bolt Swagstore",
				"manufacturer": "Bolt Factory",
				"category": "hats",
				"color": "Red",
				"size": "XXL",
				"weight": {
					"weight": 22,
					"unit": "kg"
				},
				"image_url": "https://boltswagstore.com/inventory/hats/red-hat.png",
				"details_url": "https://boltswagstore.com/inventory/hats/red-hat.png",
				"type": "physical",
				"taxable": true,
				"discounts": [],
				"included_in_subscription": false,
				"subscription_id": "00000000-0000-0000-0000-000000000000",
				"item_details": []
			}
		],
		"discounts": [],
		"shipping_address": {
			"id": 0,
			"user_id": "",
			"first_name": "Juan",
			"last_name": "Rodríguez",
			"phone": "+578315263363",
			"identity_document": "",
			"lat": 0,
			"lng": 0,
			"address1": "Avenida Carrera 72 80",
			"address2": "94",
			"city": "Bogota",
			"zipcode": "110110",
			"state_name": "Bogota",
			"country_code": "CO",
			"additional_description": "",
			"address_type": "",
			"is_default": false,
			"created_at": "2025-01-20T16:49:38Z",
			"updated_at": "2025-01-20T16:49:38Z",
			"identity_document_type": "",
			"email": "[email protected]",
			"state_code": "",
			"country": "CO"
		},
		"shipping_options": null,
		"user_instructions": "",
		"metadata": {},
		"status": "pending",
		"payment": {
			"data": {
				"amount": {
					"amount": 2100000,
					"currency": "COP"
				},
				"metadata": {
					"authorization_code": "",
					"reference_transaction_id": ""
				},
				"from_card": {
					"card_brand": "",
					"first_six": "",
					"last_four": "",
					"bank_name": "",
					"country_iso": "",
					"credential_source": ""
				},
				"updated_at": "2025-01-20 16:49:38.673262908 +0000 UTC",
				"method_type": "bank_transfer",
				"merchant": {
					"store_code": "all",
					"id": "2fe8d31e-f434-4628-869e-e894c13de929"
				},
				"created_at": "2025-01-20 16:49:38.67239479 +0000 UTC",
				"id": "d81fe7bf-748b-4a7a-bc8f-7be98c8ae748",
				"processor": "payu_pse",
				"customer": {
					"email": "[email protected]",
					"id": "56c3241c-5a7d-4f1b-99b6-b78cb78286a4",
					"first_name": "",
					"last_name": ""
				},
				"status": "pending",
				"reason": "",
				"external_transaction_id": "29e58cbf-051c-487a-8e3b-c37cb22be349",
				"authorization_bank_transfer": {
					"qr": "",
					"token": "",
					"expiration_date": "",
					"redirect_url": "",
					"reference": "4537041",
					"description": "Bank transfer transaction",
					"bank_name": "BANCO UNION COLOMBIANO",
					"external_transaction_status": "PENDING"
				},
				"merchant_payment_processor_name": "",
				"authorization_code": "",
				"installment_interest_calculations": null,
				"next_action": {
					"action": "authorization_bank_transfer",
					"authorization_bank_transfer": {
						"qr": "",
						"token": "",
						"expiration_date": "",
						"redirect_url": "https://sandbox.api.payulatam.com/payments-api/pse-caller?enc=aHR0cHM6Ly9yZWdpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFVXNlclJlZ2lzdGVyL1N0YXJ0VHJhbnNhY3Rpb24uYXNweD9lbmM9dG5QY0pITUtsU25tUnBITThmQWJ1em5HaEgySlNDcjQ5V1Y4YUttOGQ0eUJ4d0RvSmlrRGEwNFBjZE9Ca0JxSiMjanJvZHJpZ3VlekBnbWFpbC5jb20jIyMj",
						"reference": "",
						"description": "",
						"bank_name": "",
						"external_transaction_status": ""
					},
					"url": ""
				}
			}
		},
		"gift_card": [],
		"redirect_url": "",
		"webhook_urls": null,
		"total_discount": 0,
		"display_total_discount": "COP 0,00",
		"shipping": null,
		"cash_change": 0,
		"shipping_method": null,
		"shipping_methods": [],
		"timezone": "",
		"scheduled_at": "",
		"billing_address": {
			"id": 0,
			"user_id": "",
			"first_name": "Juan",
			"last_name": "Rodríguez",
			"phone": "+578315263363",
			"identity_document": "",
			"lat": 0,
			"lng": 0,
			"address1": "Avenida Carrera 72 80",
			"address2": "94",
			"city": "Bogota",
			"zipcode": "110110",
			"state_name": "Bogota",
			"country_code": "CO",
			"additional_description": "",
			"address_type": "",
			"is_default": false,
			"created_at": "2025-01-20T16:49:38Z",
			"updated_at": "2025-01-20T16:49:38Z",
			"email": "[email protected]",
			"identity_document_type": "",
			"external_number": "",
			"internal_number": "",
			"country": ""
		},
		"payment_link": "",
		"display_shipping_tax_amount": "COP 0,00",
		"display_total_tax_amount": "COP 2.000,00",
		"shipping_tax_amount": 0,
		"total_tax_amount": 200000,
		"user_id": "",
		"include_payment_options": [],
		"redirect_urls": {
			"success": "",
			"pending": "",
			"error": "",
			"fallback": "",
			"close": ""
		},
		"created_at": "",
		"updated_at": "",
		"payer_info": null,
		"discount_amount": 0,
		"shipping_discount_amount": 0,
		"device_fingerprint": "",
		"expired_at": "",
		"version": "0",
		"fraud": null,
		"display_total_interest_amount": "",
		"payment_method": "",
		"token": "",
		"statement_descriptor": "",
		"browser_details": {
			"screen_height": 0,
			"screen_width": 0,
			"user_agent": "Mozilla/5.0 (Windows; U; Windows NT 6.3) AppleWebKit/532.0.1 (KHTML, like Gecko) Chrome/19.0.871.0 Safari/532.0.1",
			"ip_address": "41.3.66.146",
			"color_depth": 0,
			"java_enabled": false,
			"java_script_enabled": false,
			"language": "",
			"time_zone_offset": 0,
			"accept_header": ""
		}
	}
}

2.1 - Redirection to PSE

Once the user is redirected to the given URL, they will be prompted to complete the bank transfer through the PSE platform. After completing the transaction, the user will be redirected to the page specified by the merchant in the Purchase V2 request.

Finally, Deuna's system will be listening for Webhooks coming from PayU, which powers our integration, regarding the final status of the transaction. However, at the same time, Deuna's system continually performs polling to the transaction until it gets a final status.

2.2 - Expected statuses

After PSE redirects the user back to the page specified by the merchant, the processor will send Deuna's system updates through Webhooks, regarding the final status of the transaction. To learn more about Webhooks, check our guide. Moreover, Deuna's system continually performs polling to the transaction until it gets a final status.

After creating a transaction for an order, it will pass through the following statuses:

  • pending, refers to the status assigned when the transaction is recently created. To obtain a final status, the merchant must redirect the user to the URL given by the processor to complete the PSE transaction.
  • processed, refers to a final status after completing the PSE transaction successfully. In this case, the status of the order will be succeeded.
  • denied, refers to a final status after the PSE transaction failed or it was abandoned by the user.

Keep in mind that, these statuses will be accessible through the order.payment.data.status property from our Purchase endpoint response.

Sandbox Environment

1 - Testing Data

In order to test your integration in Deuna's Sandbox environment, the merchant must send the following inputs to be able to process a PSE transaction through PayU's Sandbox environment:

{	
	"payment_source": {
		"method_type_specific_fields": {
			"pse": {
				"financial_institution": "1022",
				"financial_institution_name": "BANCO UNION COLOMBIANO"
			}
		}
	}
}

The response from PayU will return a redirection URL to complete the transaction in their Sandbox environment for PSE. The step-by-step to complete the redirection process in Sandbox will be explained in the next section.

2 - Redirection process

  1. The user will be redirected to enter its email address, which for testing purposes must enter the [email protected]and then click the Ir al Banco button to proceed.
  1. The user enters the PSE sample Frontend, in order to move forward press the Debug button.
  1. The user confirms the transaction by filling the following fields:
    1. bankProcessDate, which must have the same date as soliciteDate field.
    2. transactionState, refers to the expected final status for the transaction. If the merchants wants to test different paths, make sure to use the options in the dropdown menu.
    3. authorizationID, which must have the value 12 to proceed.
      After completing the form, the user should press the Call button to set the final status to the transaction.
  1. The user presses the Return to PPE to execute the redirection to the URL set by the merchant.

Airline Data

For merchants in the airline industry, the PSE integration allows them to send the following information about the ticket being booked by their users, through these fields from the Order of their users:

Airline informationDeuna field
Passenger Name Record (PNR)order.airline_information.booking_items[].pnr
IATA code of the airline operating the flightorder.airline_information.booking_items[].legs[].origin.iata_code
IATA code of travel agency booking the flightorder.airline_information.booking_items[].ticketing_travel_agency.iata_code

Updated about 1 month ago