Create a PSE Avanza Transfer

PSE (Pagos Seguros en Línea) is Colombia's centralized bank transfer system. The PSE Avanza modality allows your Colombian customers to make online payments by debiting the amount directly from their bank accounts securely.

This documentation details the parameters required to generate a PSE Avanza transaction through the PagSeguro International (PSI) API.

Payment flow

Recommended flow

Display the bank list: Present the list of available PSE banks to the customer and capture their selection.
Create the transaction. Send a POST /v3/transactions with charge.method: "PSE_AVANZA" and the customer's bank_code.
Redirect the customer. Use the redirect URL returned in the response to send the customer to PSE's bank portal for authentication.
Wait for the webhook. PSI will POST the final status (APPROVED or REJECTED) to your notification_url.
Display the result. Redirect the customer to your success or failure URL based on the webhook status.

Endpoint

POST /v3/transactions

Headers

Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {{UUID4}}

Step 1: Make a request

Key fields

Object / Parameter	Required	Description
`integration`	Yes	Transaction settings and return URLs.
`integration.reference`	Yes	Unique reference ID or code for the order in your system.
`integration.notification_url`	Yes	Webhook URL where PSI will send status updates.
`integration.language`	Yes	Payment interface language (e.g., `es_CO`).
`integration.redirect_urls`	Yes	URLs for user redirection after the flow.
`charge`	Yes	Payment method specifications.
`charge.country`	Yes	ISO country code. Must be `CO` for Colombia.
`charge.method`	Yes	Payment method. Must be `PSE_AVANZA`.
`charge.pse_avanza`	Yes	Object containing PSE-specific details.
`charge.pse_avanza.bank_code`	Yes	Clearing code of the bank selected by the customer (e.g., `"1059"`).
`payer`	Yes	Information about the customer making the payment.
`payer.address`	Yes	Payer's address (street, number, district, city, etc.).

Request example

{
  "integration": {
    "reference": "REF-XXX-1234567890",
    "notification_url": "https://www.merchantwebsite.com/notify? type=transaction",
    "language": "es_CO",
    "redirect_urls": {
      "success": "https://example.com/payment/success",
      "failure": "https://example.com/payment/failure"
    }
  },
  "order": {
    "currency": "COP",
  },
  "charge": {
    "country": "CO",
    "method": "PSE_AVANZA",
    "pse_avanza": {
      "bank_code": "0000"
    }
  },
  "payer": {
    "address": {
      "street": "Cl. 77",
      "number": "112",
      "complement": "",
      "district": "Bogota",
      "state": "BO",
      "city": "Bogota",
      "country": "CO",
      "zip-code": "110541"
    }
  }
}

Step 2: Process the API Response

The API response will confirm the creation of the payment intent. For PSE, the customer usually needs to be redirected to the bank's interface to complete the transfer. The return will detail the processed data.

Key fields

Object / Parameter	Required	Description
`integration`	Yes	Confirmation of the integration data sent.
`integration.redirect_urls`	Yes	Success and failure URLs for final redirection.
`order`	Yes	Details of the order processed by the API.
`order.currency`	Yes	Processed currency (`COP` for Colombian Pesos).
`charge`	Yes	Confirmation of the registered payment method.
`charge.country`	Yes	Country (`CO` for Colombia).
`charge.method`	Yes	Payment method (`PSE_AVANZA`).
`charge.pse_avanza`	Yes	Confirms the registered `bank_code` (e.g., "0000").
`payer`	Yes	Consolidated payer data.
`payer.person.document`	Yes	Contains type (e.g., CE) and document number.

Response example

{
  "integration": {
    "reference": "Ref-9d52a4be-dd1d-4644-b83c-5bb5873db992-test-glauco4",
    "notification_url": "https://www.merchant.com/notify",
    "language": "pt_BR",
    "redirect_urls": {
      "success": "https://www.merchant.com/success",
      "failure": "https://www.merchant.com/failure"
    }
  },
  "order": {
    "currency": "COP",
    "items": [
      {
        "quantity": 1,
        "description": "Test",
        "unit_price": 4000
      }
    ]
  },
  "charge": {
    "country": "CO",
    "method": "PSE_AVANZA",
    "pse_avanza": {
      "bank_code": "1059"
    }
  },
  "payer": {
    "email": "[email protected]",
    "ip": "64.237.155.62",
    "person": {
      "name": "JOAO DA SILVA",
      "birth_date": "1999-11-04",
      "document": {
        "type": "CE",
        "number": "Z778899"
      },
      "phone": {
        "country_code": "59",
        "number": "6999343434"
      }
    },
    "address": {
      "street": "Avenida Brasil",
      "state": "PR",
      "city": "Maringá"
    }
  }
}

Next steps

Redirection: The customer must be redirected to the bank's interface to authenticate the transaction.
Webhooks: Wait for the final status update at your notification_url (e.g., PENDING → APPROVED or REJECTED).