PSE via direct API

This page includes the steps necessary to integrate PSE using the DEUNA API.

Use the V2 endpoint for direct API integrations.

📘

For more information, refer to the Payments API.

V2 purchase

V2 purchases perform the two steps in a single endpoint by adding the order information in the request.

The V2 purchase process goes as follows:

  1. User calls POST v2/merchants/order/purchase with the order information in the CURL request.
  2. The internal service creates the order and performs the purchase operation.

Integrate PSE by API

Direct API integrations follow the V2 process.

1. Make a V2 PSE purchase

Make a request to the V2 Purchase endpoint.

To make a PSE purchase with Deuna, the V2 payload must contain the following:

  • The order data must include the order information.
  • Full name
  • Document number
  • Document type
  • Phone number
  • Person type (natural or legal)
  • Bank
  • Callback URL to redirect the user to your page

This table shows fields required to perform a PSE transaction:

FieldDescriptionExample
payer_infor.person_typeType of person, either natural or legal.LEGAL_PERSON
pse.financial_institutionCode of the selected bank.1022
pse.financial_institution_nameName of the bank.BANCO UNION COLOMBIANO
callback_urls.on_successRedirection URL after completing the PSE transaction.https://example.com/
browser_details.ip_addressIP address from the browser used by the user.155.95.122.206
billing_address.identification_typeType of identity document. Available documents are: CC,CE, TI, PP, NIT, RCandDE.CC
billing_address.identificationIdentification number of the user.1234567890
billing_address.first_nameFirst name of the user.Juan
billing_address.last_nameLast name of the user.Pérez
billing_address.phonePhone number in E.164format.+14155552671
billing_address.cityCity for billing the user.Bogotá
billing_address.street1Primary address information for billing the user.Avenida Carrera 72 80
billing_address.street2Apartment and suite information for billing the user.94
{
	"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"
		}
	}
}

2. Redirect the user

After performing the purchase, the API responds with a redirection URL in the authorization_bank_transfer node.

Use the URL to redirect the user to complete the bank transfer through PSE.

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": ""
		}
	}
}

📘

For the final status of the transaction, DEUNA continuously listens to webhooks coming from PayU, which powers our integration with PSE. DEUNA performs polling to the transaction until it gets a final status.