Create a hosted PayURL checkout

The PayPaga PayURL is a customized checkout webpage to allow the selection of a payment method, entering any required information and submitting the payment.

The workflow steps are listed below:

Call OAuth 2.0 Token Generation and retrieve OAuth2.0 token.

Using the OAuth2.0 token, call the Get PayURL endpoint to get a new PayPaga PayURL based on the parameters provided in the request.

Redirect the user to the generated PayPaga PayURL.

The PayPaga PayURL will present to the user a list of payment methods previously approved by the merchant for the specified country.

Then, the user selects their preferred payment method, enters any required information and submits the payment.

Upon successful submission, the payment result is displayed, including instructions for asynchronous payments. A new transaction with status of PENDING will be created in the system.

Redirect the user to the generated PayURL

The PayURL can be loaded directly in a new tab or browser window.

In case the PayURL is going to be embedded into the merchant's website using an <iframe> use the following code:

⚠️ It is important to include the allow="clipboard-write" attribute in the <iframe> to allow the user to use the copy-to-clipboard functionality.

⚠️ Please keep in mind, if using <iframe> in your integration, certain methods (listed below) will block communication due to security purposes. If you wish to also implement these methods, new tab redirection is recommended.

Colombia: PSE, Nequi, Daviplata, RappiPay, Dale, Movii, Transfiya

Chile: Khipu

El Salvador: Banco Agrícola, Banco Cuscatlán

Guatemala: Banco Industrial, BAM Transfer

This service initiates the PayPaga PayURL flow where, if successful, returns a new PayURL to the user to be redirected to for payment completion.

Custom Payment Method List

It is possible to narrow down the list of payment options the user can choose from, by using the parameter payment_method_codes as follows:

These are the possible scenarios:

If the list contains an invalid method, an error will occur and no PayURL will be generated.

If the list contains valid methods, the PayURL web page will show only those as payment options.

If the list contains a single valid option and that option requires additional information to be entered by the user, the PayURL will show the correspondent fields to enter that information.

If the list contains a single valid option and that option doesn't require any additional information, the PayURL won't display the payment options step. Instead, the payment request will be submitted automatically using the pre-selected payment option and the payment result will be displayed, including instructions for asynchronous payments.

Customer Data

This API enables known customer data to be supplied to streamline the customer experience and optimize conversion by minimizing manual data entry.

Where all required customer data for a payment method is supplied and validated the customer will automatically receive instructions to complete the payment alleviating the need for any intermediate manual data entry steps.

Error codes for Create PayURL

HTTP status	Error code	Description
400	BAD_REQUEST	Failed to parse the request body
400	VALIDATION_ERROR	Request validation failed
400	CONFIGURATION_NOT_AVAILABLE	No configuration available for the requested parameters
401	UNAUTHORIZED	Missing or invalid authorization token
409	MERCHANT_REFERENCE_ALREADY_EXISTS	Merchant transaction reference already exists
500	INTERNAL_ERROR	Unexpected server error

Request

Authorization

OAuth 2.0

Client Credentials

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Token URL: https://api.paypaga.com/oauth2/token

Header Params

Body Params application/jsonRequired

Examples

curl --location 'https://api.paypaga.com/v2/pay-urls' \ --header 'DisablePartnerMock;' \ --header 'Content-Type: application/json' \ --data-raw '{ "country": "BR", "currency": "BRL", "amount": 125.5, "merchant_transaction_reference": "TRX-2026-0001", "merchant_order_reference": "ORDER-2026-0001", "merchant_customer_id": "customer@email.com", "allowed_payment_methods": [ "pix", "bank_transfer" ], "predefined_fields": [ { "payment_method": "pix", "fields": { "document_number": "12345678909" } } ], "return_urls": { "success_url": "https://merchant.com/payment-success", "pending_url": "https://merchant.com/payment-pending", "failure_url": "https://merchant.com/payment-failure" } }'

Create a hosted PayURL checkout

Redirect the user to the generated PayURL#

Custom Payment Method List#

Customer Data#

Error codes for Create PayURL#

Request

Responses

Redirect the user to the generated PayURL

Custom Payment Method List

Customer Data

Error codes for Create PayURL