PSE via Direct API | DEUNA Docs

On this page

V2 purchase
Integrate PSE by API

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

Use the V2 endpoint for direct API integrations.

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:

User calls POST v2/merchants/order/purchase with the order information in the CURL request.
DEUNA creates the order and performs the purchase operation.

Integrate PSE by API#

Direct API integrations follow the V2 process.

1. Get available banks

As a prerequisite to perform a Purchase, the user must select the bank to perform the transaction from.

Make a request to the Merchant Payment Methods endpoint to obtain the information.

The resulting response object will have the following structure:

JSON

{
  "@type": "type.googleapis.com/external_merchant_api.v1.GetPaymentMethodsResponse",
  "data": [
    {
      "enabled": true,
      "method_type": "bank_transfer",
      "processor_name": "payu_pse",
      "specific_fields": {
        "financial_institutions": [
          {
            "id": "1081",
            "description": "BANCO AGRARIO DESARROLLO",
            "url": ""
          },
          {
            "id": "1813",
            "description": "SANTANDER CONSUMER COLOMBIA",
            "url": ""
          }
        ]
      },
      "input_schema": [],
      "labels": {
        "es": ""
      },
      "exclude_cvv": false,
      "excluded_franchises": [],
      "extra_params": {},
      "installments": [],
      "credentials": {
        "public_api_key": "",
        "external_merchant_id": "",
        "customer_token": ""
      },
      "google_pay_credential": null,
      "stored_payment_methods": [],
      "id": "00000000-0000-0000-0000-000000000000",
      "payment_centers": [],
      "payment_provider": ""
    }
  ]
}

Inside the specific_fields object, there's an object called financial_institutions containing an array of objects with the following structure:

JSON

{
  "id": "1813",
  "description": "SANTANDER CONSUMER COLOMBIA",
  "url": ""
}

How to output the information to the user?

Make sure to output the array of object by using the description field as the label. Once the user selects an option, make sure to the id and description fields to fill the bank information required for the Purchase.

2. 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:

Field	Description	Example
`payer_infor.person_type`	Type of person, either natural or legal.	`LEGAL_PERSON`
`pse.financial_institution`	Code of the selected bank.	1022
`pse.financial_institution_name`	Name of the bank.	`BANCO UNION COLOMBIANO`
`callback_urls.on_success`	Redirection URL after completing the PSE transaction.	`https://example.com/`
`browser_details.ip_address`	IP address from the browser used by the user.	155.95.122.206
`billing_address.identification_type`	Type of identity document. Available documents are: `CC`,`CE`, `TI`, `PP`, `NIT`, `RC`and`DE`.	`CC`
`billing_address.identification`	Identification number of the user.	1234567890
`billing_address.first_name`	First name of the user.	Juan
`billing_address.last_name`	Last name of the user.	Pérez
`billing_address.phone`	Phone number in `E.164`format.	+14155552671
`billing_address.city`	City for billing the user.	Bogotá
`billing_address.street1`	Primary address information for billing the user.	Avenida Carrera 72 80
`billing_address.street2`	Apartment and suite information for billing the user.	94

json

{
	"order_type": "DEUNA_CHECKOUT",
	"payer_info": {
		"email": "jrodriguez@gmail.com",
		"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": "jrodriguez@gmail.com",
			"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": "jrodriguez@gmail.com",
			"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"
		}
	}
}

3. Redirect the user

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

Take the URL from the authorization_bank_transfer node.
Redirect the user to the URL.
Wait for the user to complete the payment.

The User completes the payment in PSE
Listen to the PayU webhooks to confirm the payment.

Response

JSON

{
	"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": "jrodriguez@gmail.com",
			"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": "Benny.Reynolds55@yahoo.com",
					"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": "jrodriguez@gmail.com",
			"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": ""
		}
	}
}