Create an e-Wallet Transaction

This guide outlines the general steps to create an e-wallet transaction using the PagSeguro platform. You'll learn how to collect payer details, initiate a payment, and redirect the customer to complete the transaction. The flow described here applies broadly to all supported e-wallets. For provider-specific details, see the individual guides for PagBank, PayPal, and PagSeguro.

e-Wallet Payment Flow

1. Customer → Merchant: The customer fills in and submits all required payment information on the merchant’s website.
2. Merchant → PagSeguro: The merchant sends a request to the Create transaction endpoint.
3. PagSeguro → Merchant: PagSeguro creates the order and responds with a transaction code and a payment URL.
4. Merchant → Customer: The merchant redirects the customer to the PagSeguro payment URL.
5. Customer → Payment Provider: The customer completes the payment through the selected payment method's website.
6. Payment Provider → Customer: After completing or canceling the payment:
   • On success, the customer is redirected to the merchant's success URL.
   • On failure or cancellation, the customer is redirected to the merchant's fail URL.

Follow the steps below to create an e-wallet payment:

Step 1: Collecting Payer Details

The customer must provide all mandatory information, such as name, email, document type and number, and address.

🚧

Delivery Address

Payer address is required when the cart item type is physical.

Step 2: Requesting a PostPay Payment

After the customer sends their information, you can use the Create transaction endpoint to submit it to PagSeguro. There are three different e-wallets available for the e-wallet payment method.

Below is an example request and response:

{
  "transaction": {
    "reference": "REF-XXX-1539093014330",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR",
    "redirect-urls": {
      "success": "https://billing.checkout.com/direct?return=1",
      "fail": "https://billing.checkout.com/direct?cancel=1"
    }
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "e-wallet",
        "sub-type": "pagseguro"
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "98765432101"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 302",
      "district": "Bairro dos Testes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 302",
      "district": "Bairro dos Testes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

{
  "transaction": {
    "code": "111115949",
    "reference": "REF-XXX-15390930143123",
    "amount": 100.00,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2018-10-09T10:50:09.422046071-03:00",
    "payment-url": "https://gateway.boacompra.com/ewallet.php?token=B47818A1788C8DF39ECB"
  }
}

📘

Reason Codes

If the request fails, the API will return an HTTP status code other than 200. The response body will include an errors array with descriptive messages and corresponding error codes.

For the full list of possible error codes, see the Reason Codes reference.

Step 3: Redirecting Customer to e-Wallet Page

With the response from the Create transaction endpoint, you can redirect your customer to the URL returned in the payment-url object.

Available Payment Methods